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MIT 
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MACSYMA 

1 Introduction 



MACSYMA (Project MACs SVmbolic Manipulation System) is a large computer 
programming system written in LISP [Mnl] used for performing symbolic as well as 
numerical mathematical manipulations. It is being developed by the Mathlab Group 
of the MIT Laboratory for Computer Science (formerly Project MAC). 

With MACSYMA the user can differentiate, integrate, take limits, solve 
systems of linear or polynomial equations, factor polynomials, expand functions in 
Laurent or Taylor series, solve differential equations (using direct or transform 
methods), compute Poisson series, plot curves, and manipulate matrices and 
tensors. MACSYMA has a language similar to ALGOL-60 to permit the user to 
write his own programs for transforming symbolic expressions. 

This manual is intended to be a complete reference for the principal features 
of MACSYMA as of the date shown on the cover. !t is not meant to be a tutorial 
nor does it discuss all of the issues involved in the efficient manipulation of 
algebraic expressions. New features under development are, for the most part, 
not mentioned. 

The user who is unacquainted with certain concepts of computer programming 
may find this document difficult on first reading. The novice will benefit by first 
reading the MACSYMA Primer [Mo5] and An Introduction to ITS for the MACSYMA 
User [Lewi]. This document serves as both a reference manual and as a user's 
manual. When it is used as a user's manual, any sections not of interest should be 
skipped. Sections which may be passed over on first reading are indicated by the 
symbol [] around the section number. 

It is recommended that this manual be re-read from time to time after the 
user has worked with MACSYMA so that certain parts which were unclear on 
prior readings will be better understood in the context of increased familiarity 
with the system. 

In a programming system such as MACSYMA there are often many ways to go 
about solving a given problem as well as many constraints and frustrations which 
must be dealt with. Some ways will not succeed due to space or time constraints 
and others may work but may be unnecessarily slow. Frequently a better 
understanding of the computer facilities will lead to a reformulation of the problem 
lending itself to a much improved solution. For some insight into the subject see 
[Al, Mol,Mo2]. 
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1 • 1 Logging in and out 



MACSYMA is implemented on DEC PDP-10 computers which use the iTS 
operating system and on Honeywell 6180 computers using the Multics operating 
system The following section concerns the protocol for usage on the PDP-10 at 
MIT known as the MC (MACSYMA Consortium) machine. Appendix I of this manual 
concerns the use of MACSYMA on Multics. 

A user may gain access to the PDP-10 computer at MIT by (1) finding a 
terminal connected to it or (2) finding one on which he can dial to it over public 
telephone lines or (3) logging into it over the ARPA network. Once this is done 
the user should be communicating with the ITS time sharing system. To login he 
should type a control-Z (depressing the control key while typing the letter Z) 
which loads in DDT [Lewi] (the top level system program). Then he should type 
:LOGIN followed by a space and his user name. (All system commands, i.e. those 
which begin with a colon, are terminated by a carriage return). At this point the 
user can start up any of several system programs available (PEEK, TECO, etc.) by 
typing a : followed by the name of the program. In particular :MACSYM loads in 
and begins execution of MACSYMA. After printing some descriptive information, 
including the version number, MACSYMA prints (Cl) which means that it is ready 
to accept input from the user. The entire sequence is shown below with the 
computer's output indented. *char * means the control key is to be held down 
while the next character char is typed 

MC ITS nnnn CONSOLE 11 FREE 2 



^7 3 










MC 


ITS I 


innn 


ODT 


mmoi 


: LOGIN 1 


SMITH 








:MACSYM 










Th 


is 1s 


MACSYMA 


vw 



1 . The user should note that there is a separate character, A , which is often used 
for exponentiation (as in line (Cl) below). Although the two characters print in 
the same way the user should have no difficulty distinguishing between them. In 
the example, the ""5" could not be "control-5" since the context strongly 
indicates exponentiation. 

2. nnnn represents a version number which changes from time to time; ii identifies 
the console. 

3. Not printed on console 
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(Cl) NROOTS(2*X*5-X+5,-4,8); 
(01) 1 

44130) .CALL 44154 (IOT) 
: LOGOUT 

MC ITS nnnn CONSOLE i1 FREE 



In line (Cl) the user has typed a command which asks for the number of 
real roots between -4 and 8 of a quintic polynomial. In line (Dl) MACSYMA has 
printed the answer. The ^Z causes an exit from MACSYMA to DDT after which the 
system typed "CALL 44154 (IOT)- (meaning that MACSYMA was waiting for input 
when interrupted). Typing :L0G0UT causes the system to delete all the user's 
jobs (in this case MACSYMA was the only job) and to log him out of ITS. When 
the user finishes he should always log the console out before he leaves. 



1.2 Genera! Information 



Command lines to MACSYMA are strings of characters representing 
mathematical expressions involving equations, arrays, functions, and programs. 
Extra spaces, tabs, and all carriage returns are ignored (except when these occur 
in quoted strings). 

Command lines are terminated by ";" or "S" (dollar sign). A V causes the 
command line to be evaluated and the result displayed. The terminator "S" causes 
the command line to be evaluated but the result is not displayed. 

When typing command lines, depressing the "rubout" or "delete" key deletes 
the previous character (on hardcopy devices and displays which cannot backspace, 
the deleted character is echoed). By typing "control-K" , the user obtains a copy 
of the current command line free of any echoed erasures. The two characters 
delete the whole command line, and cause the line number to be redisplayed. 



99 



The command (input) lines are indexed by labels of the form "(Ci)" where i is 
incremented with each new command line typed by the user. Similarly, the results 
of computations are also indexed. There are two types of output lines. The 
ordinary output line is indexed by a label of the form "(Di)" ; thus, usually the ith 
input-output pair will be (Ci)-(Di). Sometimes,however, a computation produces 
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several intermediate results (for example, several solutions to an equation); it is 
convenient to be able to reference these intermediate lines of output. They are 
indexed by labels of the form "(Ej) M where j is incremented by one for each 
intermediate line. For example, 



<C1) S0LVE(X~2 ♦ B*X + C, X); 

2 
SQRT(B - 4 C) + B 

(El) X * 

2 
2 
B - SQRT(B .- 4 C) 

(E2) X = 

2 
(02) [El. E2J 

Note that there is no line Dl since intermediate results were produced and 
thus the line index was incremented. The general pattern of indexing is of the 
form 

Ci, Ei,Ei+l,...,Ej, Dj . 

A command line may refer to the results of any previously indexed line (even 
if it was not displayed) through the use of the line labels. For example, the user 
might say SUBSTITUTE(7,B,E2); which would substitute 7 for B in the expression 
E2 above. The immediately preceding D-line is conveniently referenced by the 
symbol "7.". 

If the input line contains a syntax error, it will be reprinted and the location 
of the error will be indicated as closely as possible by a special string, ***8*** . 

From a C-Iine, the user in need of assistance can type: 



SEND(message) which will send your message to some MACSYMA system 
programmer who is logged in at that time. If no approriate recipient is 
available, the message will be sent to MACSYMA's mail file where it will be 
seen and will be answered. If the message consists of more than one word, 
therv vessage must begin and end with double quotes. 
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BUG(message) sends a bug note to MACSYMA. If more than one word, message 
must begin and end with double quotes. 



MMUmessage) sends mail to MACSYMA using the syntax above. 



DESCRlBE(command) takes as argument any MACSYMA command and prints out 
the relevant portion of the MACSYMA manual. 



EXAMPLE(command) gives examples (in DEMO mode) of the use of selected 
functions in MACSYMA. 



PRIMERS provides an on-line primer for the novice including an introduction to 
MACSYMA syntax, assignment and function definition, and the simplification 
commands. 



x.o lctcis vi \suiiirui 



When :MACSYM is typed, a LISP system extended with MACSYMA programs is 
loaded into main memory from auxiliary storage. Special top level programs read 
in, evaluate, simplify, and display the user's expressions. All of the functions to 
be presented in subsequent sections are actually LISP programs which, when they 
are called, may invoke many other LISP programs in a process that is invisible to 
the user. 

Switching between DDT, MACSYMA, and the LISP system in which it is 
embedded is accomplished by typing the following characters: 

Control-^ typed while in MACSYMA causes LISP to be entered. The user can 
now type any LISP S-expression and have it evaluated. Typing (CONTINUE) or ~G 
(control-G) causes MACSYMA to be re-entered. 

~Z causes an immediate exit to DDT. If one is already in DDT then ?? is 
printed. At this point the user can run some other program like PEEK or TECO 
[Lewi]. When in DDT, typing :CONTINUE causes the current job to be resumed. 
(JOB MACSYM should be typed first if the user wishes to re-enter a MACSYMA 
which is not the current job). 



6 MACSYMA 

1.4 Miscellaneous Information 



rues mi mc no syaicin nave iwo names cdt-n ui at ffiusi o cnaraciers. i ney 
are referenced by giving the two names as well as the device (default is DSK) and 
the directory name where the file resides (default is the same as the user's login 
name). A > sign may be used for the second file name and stands for the name 
which is the largest numerically if there exists a file with the given first name and 
a numeric second name; otherwise, the > sign represents the "greatest" name in 
an alphanumeric sense. A < sign may be similarly used for the "least" name. 

Any of the four descriptors (1st name, 2nd name, device, user) may be 
omitted and either the default or the value given in a previous command (if there 
was one given) will be used. 

For those without a disk directory of their own, the one named USERS is 
available. When placing a file on this directory the user should indicate in some 
manner (such as by the first file name) the name of the user who created it. 

There is a special mail file on the ITS system for holding comments from users 
which are of general interest and for listing changes to MACSYMA which occur 
from time to time. The DDT command :MAIL MACSYM followed by a carriage return 
and text terminated by a control-C is used to place comments in this mail file. The 
user's login name and time of message are added automatically. (Control-D may 
be used to cancel this or any other DDT command prematurely). If the user 
encounters any bugs in MACSYMA then he should report these in MACSYMA mail. 
Mail may also be sent to other users by using the :MAIL command followed by the 
user's login name. If the user has received mail the message —MAIL-- will 
appear on his console after he logs in. Typing a space will cause the mail to be 
printed. The DDT command PRMAIL MACSYM is used to print out the MACSYMA 
mail file The user should do this occasionally to be informed of changes to the 
system and of other users' comments. iPRMAIL may also be used to print out any 
user's mail by following it with the user's login name. Control-S may be used to 
silence the printout. In addition, the command :PRINT MACSYMjUPDATE > may be 
used to print a file describing updates to MACSYMA since the last version of the 
manual The update file should be checked regularly so the user can be informed 
of changes to MACSYMA. 

For further information on DDT commands see [Lewi]. Typing :? will list the 
commands with a brief description. In particular, one command worth noting is 
;KILL which kills the current job. 
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An Introduction to ITS for the MACSYMA User [Lewi] and the MACSYMA 
Primer [Mo5] are very useful to the novice. 
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2 MACSYMA's Data Types and Statement Types 

This section describes the k«nH* *»' «vf n ^ ec #»;««« kiA^^VM* =«:*- • »t . 

.wws »,,c Riiiu^ vi c/spi sssiwiia Mnv^oTiviM permits ana ineir 

meanings. Chapters 5 and 6 should be referred to where necessary in order to 
clarify the examples presented Default values of options are indicated in square 
brackets, [...]. 



2.1 Numbers 

Numbers are integers, rational numbers, floating point numbers, or "bigfloats" 
Integers consist of a string of digits not containing a period; rational numbers are 
the quotient of two integers and are written as numerator/denominator; floating 
point numbers are written as in FORTRAN, i.e. strings of digits containing a period 
and optionally followed by an integer exponent beginning with the letter E; and 
bigfloats are written exactly like floating point numbers except using the letter B 
rather than E (the B must be included to indicate a bigfloat). Negative numbers 
begin with a minus sign. There is no limit on the number of digits in an integer or 
rational number but non-zero floating point numbers must have absolute value 
between .14E-38 and 1.7E38 and are limited to approximately 8 digits precision 
This «s the hardware limitation of the computer. Bigfloats may have any number of 

™LZrf.^ efaU,t precision js 16 but the user can change this by setting the 
FPPREC[16] to an integer representing the desired precision. 

-17253733574534 6.023E23 -1.6E-19 

37.567834987250832568B-98 3.14159 227 

-3354665557331/66724255465544 -.780 

2.2 Names 



Names are used to designate variables, functions, and arrays. A name 
consists of a string of letters (which may include 7.) and digits. It may also include 
other characters but these must be preceded with a \ when typed in. Names can 
be o- any length and must begin with a letter (unless the leading character is a \). 
Lower case letters may be typed, but they are normally converted into, the 
corresponding upper case letters. 



MACSYMA 2.2 Names 

XPI EPSILON X10Y30ISASTRANGENAME \*SPECIAL 
2.3 Quoted Strings 



A string of characters of any length may be constructed by enclosing the 
string in quotation marks. To include a quotation mark, semicolon, or dollar sign in 
the string it is necessary to precede it with a \ when typed in. Quoted strings 
are useful as messages (such as those giving instructions for entering data) or in 
as descriptive titles for printed data. 

Certain names that are reserved because of their function as keywords 
(operators or delimiters) are listed in Appendix II. If these are used out of their 
normal context they must be quoted. 



"INPUT AMOUNT IN \t" "RIEMANN'S \"ZETA\* FUNCTION' 

2,4 Atomic Variables and Assign m ent 



A name which may be assigned an arbitrary value is a variable. A variable 
might or might not be subscripted (see 2.6.2). A non-subscripted variable is 
designated as an "atomic variable". Atomic variables are assigned values by 
writing the name of the variable followed by a : followed by an expression 
representing the value to be assigned to the variable. A variable can be assigned 
a new value at any time. The value of a variable can be a number, a matrix, a 
list, or any MACSYMA expression. If a variable is not assigned a value then it just 
represents itself. There are many variables which have already been assigned 
values. These are called "MACSYMA" variables or options. They are provided in 
order to give the user some control over the way in which MACSYMA performs 
its operations. The user should choose names other than these for his variables. 
The index to this manual distinguishes these "MACSYMA" variables and options 
with a colon (":") between the variable and its default value. In the text of the 
manual, the default value is indicated with square brackets as in the next 
sentence. MYOPTIONS[[]] is a MACSYMA variable— an "infolist" (see 
8.1)— -which is a list of all the MACSYMA options ever reset by the user. 

Some simple examples of assignment follow. (The comments in parentheses 
are only for the reader's benefit and are not actually typed to or by MACSYMA.) 
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Note that MACSYMA automatically assigns labels Ci to the user's input lines and Di 
to the output lines. These labels behave as assigned variables and can be 
referenced by the user. 

1 inc label expression comment 

(CI) A:16« (integer) 

(CZ) LAMBDA: -3/37$ (rational number) 

(C3) X:D1; (X is assigned the value of Dl) 

(D3) 16 

(C4) RH0:SIGMA; (since SIGMA has no value at this 

time RHO is assigned the symbol SIGMA) 
(04) SIGMA 

(C5) SIGMA: .0051 (floating point) 

(C6) RHO; (RHO still has its old value since 
(06) SIGMA it hasn't been reassigned a new one) 



Since the value assigned may be any expression it may in particular be 
another assignment and therefore multiple assignments are permitted. Thus 
A:B:C:X+1 assigns X+l to A, B, and C. 

It is important to note that the expression assigned to the variable is not re- 
copied. Only a pointer to the expression is assigned. Thus in the above example, 
only one copy of X+l is created. 

The MACSYMA variable VALUES (see 8.1) gives a list (see 
2.7) of all the user's atomic variables which have been bound (i.e. have 
been assigned values). 

The assignment operator :: assigns the value of the expression on its right to 
the value of the quantity on its left, which must evaluate to an atomic variable or 
subscripted variable (sec. 2.6.2). Thus continuing with the above examples: 

(C7) rho: : LAMBDA! (Note that the :: causes the value of 

( c-8 ) SIGMA ; LAMBDA, i.e. -3/37, to be assigned to 

(08) -3/37 the value of RHO, i.e. SIGMA.) 

(C9) VALUES; 

(D9) [A, LAMBDA, X, RHO, SIGMA] 



Operator Name 


Symbol 


factorials 


! ! ! 


exponentiation 


** or ' 


non-commutative 


AA 


exponentiation 




non -commutative 


. 


multiplication 




div'sn mult'pn 


/ * 


negation 


- 


add'n subt'n 


♦ 
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2.5 Mathematical Operators 



Mathematical expressions are constructed by using the following operators 
and also functions (see 2.6). The usage and priorities from highest to 
lowest are: 

Usage 

postfix 

Infix 

Infix 

Infix 

Infix 

prefix 

Infix 



it an operator is rererrea lo out or context it must be enclosed in quotation 
marks. 

EXPT is used to display exponentiation when the base or exponent become 
unwieldy. 

! is the factorial which is the product of all the integers from 1 up to its 
argument Thus 5! = 1*2*3*4*5 = 120. The value of the option FACTLIM[-1] 
gives the highest factorial which is automatically expanded. If it is -1 then all 
integers are expanded 

!! stands for double factorial which is defined as the product of all the 
consecutive odd (or even) integers from 1 (or 2) to the odd (or even) argument. 
Thus 8!! is 2*4*6*8 = 384. 

Period is used for non-commutative product. It must be preceded and 
followed by a space when any ambiguity can arise with respect to floating point 
numbers. Non-commutative exponentiation is used in the usual sense that M^^2 
means M . M. 

Operators of equal priority are performed left to right. Parentheses can be 
used to change the order of evaluation. Also functional application has the highest 
priority. Thus SIN(A*X"Y/Z!)"2 means (SIN(A*(X"Y)/(Z!)))"2 



12 2.5 Mathematical Operators MACSYMA 

The operands may be any MACSYMA expressions whose values are the 
correct types of data. Note that every statement in MACSYMA yields a value 
even if the value is only a trivial one. 

MACSYMA has no restriction on the mixing of modes of operands. Integers, 
rationals, floating point numbers, and bigfloats may be freely intermixed in an 
expression; when conversions are necessary, the priority of conversion is in the 
order of the types just mentioned. If floating point numbers or bigfloats of 
differing precision are combined in a operation, they will be converted to floating 
point or bigfloat numbers of the current precision by padding with zeroes or by 
dropping off low order digits and rounding. 

Floating point underflow will return 0.0 unless the MACSYMA variable 
ZUNDERFLOWfTRUE] l is FALSE in which case an error will be signaled 



2.6 Functions and Arrays 



2.6.1 Functions 



A function is written as a name followed by the arguments to the function 
separated by commas and enclosed in parentheses. The arguments may be any 
MACSYMA expressions. 

A function of a fixed number of arguments can be defined in MACSYMA by 
using the := operator. The left side of a function definition consists of the name 
of the function followed by the list of formal parameters enclosed in parentheses. 
The right side consists of the function body. When a function is called, the formal 
parameters will be bound to the actual arguments, any free variables in the 
function body will take on the values which they have at the time of the call, and 
the function body will be evaluated. It is permissible to define functions which are 
recursive to an arbitrary depth. Care should be taken when passing an expression 
which contains a variable with the same name as a formal parameter to a function 
defined with that formal parameter as circularity could result when it is evaluated 
(see 3.2). 

The MACSYMA variable FUNCTIONS is a list of all user defined non- 
subscripted functions. 



1 The square brackets enclose default options 
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The MACSYMA function DISPFUN may be used to display the definition of a 
function (see 10). 

(Cl) F(X):=X A 2+Yt 

(C2) F<2); 

(02) Y ♦ 4 

(C3) Y:7f 

(C4) F(2); 

(04) 11 

(C5) G(Y,Z):=F(Z)*3*Y; 

(05) G(Y, Z) := F(Z) ♦ 3 Y 
(C6) G(2*Y*Z,-.5); 

(06) 3 (Z ♦ 14) ♦ Z + 14.25 

(C7) FUNCTIONS; 

(07) [F(X), G(Y, Z)] 



The example involving the function G above requires some explanation. In 
going from C6 to D6 the following occurs: 

(1) The arguments to G are evaluated giving Z+14 and -.5 (Y has the value 
7). 

(2) G is then invoked and has its formal parameters bound. Y to Z+14 (the 
first argument) and Z to -.5 (the second argument). The evaluation of G then 
causes F to be invoked on the argument -.5 

(3) F has its formal parameter X bound to -.5 and returns the result of the 
evaluation X 2 +Y with the current bindings which gives Z+ 14.25 

(4) The evaluation of G continues with 3*Y which yields 3*(Z+14). This is 
added to the result from (3) and returned. 
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2.6.2 Arrays 



_, - „..*. »w ivid »u a vvrii^vviwn ui eiciTicm& uj using a single narne. 

An element of an array is referred to by a subscripted variable which is a name 
followed by a list of subscripts enclosed in square brackets. Arrays in MACSYMA 
are of two types 1 - declared or undeclared. Declared arrays are similar to 
FORTRAN arrays. The user declares the number of dimensions and indicates the 
maximum value of each subscript. The system then allocates space for the entire 
array. To declare an array the user types: 

ARRAYfnaroe, diml, dim2, ..., dimk) 

This sets up a k-dimensional array. A maximum of five dimensions may be used. 
The subscripts for the \th dimension are the integers running from to dimi. If 
the user assigns to a subscripted variable without declaring the corresponding 
array, an undeclared array is set up. 

Undeclared arrays, otherwise known as hashed arrays (because hash coding is 
done on the subscripts), are more general than declared arrays. The user does 
not declare their maximum size, and they grow dynamically by hashing as more 
elements are assigned values. The subscripts of undeclared arrays need not even 
be numbers. However, unless an array is rather sparse, it is probably more 
efficient to declare it when possible than to leave it undeclared. The ARRAY 
function can be used to transform an undeclared array into a declared array. 

Array elements can be assigned values explicitly with the : operator or 
implicitly by means of an associated function, and the values assigned may be any 
MACSYMA expression. To understand implicit assignment we must understand 
what MACSYMA does when asked to evaluate a subscripted variable. MACSYMA 
first evaluates the subscripts left to right. Then it does an array access to see if 
the requested array element already has a value. If it does, the value is returned 
If it does not, MACSYMA checks to see whether the array has an associated 
function (see below). If not, the subscripted variable (with the subscripts 
evaluated) is returned. (This is standard MACSYMA practice - if there is no value 
for a variable, the variable itself is returned when an evaluation is done.) If there 
is an associated function, the parameters of the function are bound to the given 



1. For efficient translation, the user can also inform MACSYMA of arrays all of 
whose elements are of a single type, e.g. INTEGER,BOOLEAN,FLOAT. (see 

1 U.o), 
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subscripts, and the function body is evaluated. The value of the function call is 
stored in the appropriate array element and returned. Note that once an element 
is computed by the associated function it is stored so that next time it is needed 
it will not be recomputed. A consequence of this is that unless the user uses the 
KILL, REMVALUE, or REMARRAY functions (sec. 10.3) to kill an array 
element or the entire array, the associated function will never be called a second 
time on the same arguments. Thus the user should be aware that even if he 
redefines the associated function, those values which already exist will stay 
around. Of course individual array elements can be changed by assignment at any 
time. 

These associated functions are defined with the := operator. Their definition 
looks exactly the same as ordinary function definitions, except that the 
parameters in the left side of the definition are enclosed in brackets instead of 
parentheses. 

in order to use a subscripted variable as a single entity without it being an 
array and without ever assigning a value to it, it should be prefixed by an 
apostrophe to avoid it being confused with a non-subscripted variable of the same 
name. For example SUBST(0,W,W+'W[0]). 

The MACSYMA variable ARRAYS is a list of all the arrays that have been 
allocated, both declared and undeclared. 

OlSPFUN (see 10.2) may be used to display the definition of an array 
associated function. 

ARRAYINFO (see 8.1.1) may be used to find out whether an array is 
declared or undeclared, how large it is, how many subscripts it has, and which 
elements have values in the case of an undeclared array. 

(Cl) A[N]:=N*A[N-l]t 

(C2) A[0J:lt 

(C3) A[5]; 

(03) 120 

(C4) A[NJ:=Nt 

(C5) A[6]; 

(D5) 6 
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(Note that the definition in C4 is being used because A[6] has no value up to this 
time.) 

(C6) A[4J; 

(D6) 24 



(Since A[4] was assigned a value as a result of A[5] being computed, the new 
definition is not used.) 



If one is going to define a recursive function which is to be called several 
times then if may be more efficient to use an array with an associated function for 
initialization. The reason is that once an element is computed it is stored and thus 
need not be computed again whereas with a non-subscripted function, each 
recursive call may cause a repeat of a past computation. 



2.6.3 Lambda Notation 



The LAMBDA notation is used for unnamed functions in order to indicate the 
correspondence between the variables of the function and the arguments which 
are to be substituted for them. It is useful when one desires to pass functional 
arguments to other functions or when one wants to apply a function just once 
without having to define it with :=. 

(Cl) F:LAMBDA([X,Y,Z],X A 2*Y*2*Z*2); 

2 2 2 
(Dl) LAMBDA([X, Y, Z], Z + Y ♦ X ) 

(C2) F(],2,A); 

2 
(02) A ♦ 5 

MACSYMA also permits operators to be used in a functional notation; 
however, in order not to get a syntax error they must be surrounded by "s. 



<C3) "+"(1.2. A); 

(03) A ♦ 3 
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[2.6.4] Subscripted Functions (Arrays of Functions) 



It is possible for the value of an array element to be a lambda expression. 
Thus if the assignment F[1]:LAMBDA([XPC2+1) were performed, then F[l] could 
be used in the ordinary prefix functional sense with its arguments following in 
parentheses, e.g. F[l]<3) would yield the value 10. There is an alternative syntax 
available for assigning a lambda expression to an array which introduces the 
notion of a "subscripted function". In the above case one could also type 
Ff 1](X):=X^2+1 and this would be entirely equivalent. Other elements of the array 
could be assigned different lambda expressions (or any MACSYMA expressions). 
If there is an algorithm for computing the different functions to be stored in an 
array on the basis of the subscripts alone, then one may use an associated 
function. For example, F[K]:=LAMBDA([XPCK+1). Again an alternative syntax of 
F[K](X):=X"K+1 may be used. The left side of the definition consists of the 
function name followed by the subscripts, enclosed in brackets, followed by the 
arguments, enclosed in parentheses. The subscripts (which are not evaluated at 
definition time) must be either all numeric or all symbolic. Note that subscripted 
functions are treated exactly like arrays so all of the information in sec. 2.6.2 
applies. In particular when a subscripted function is referenced, the element is 
immediately retrieved and applied to its arguments if it exists; otherwise it is 
computed (this time only) and then applied. Consequently, two evaluations of the 
definition are performed. Thus consider the definition F[K](E):=COEFF(E,X,K) and 
the call F[2](3*X"2-1). Although the user may have thought that this would 
return the coefficient of X 2 in 3*X 2 -1, i.e. 3, it will return 0. The reason is that 
F[2] is first computed by evaluating the definition yielding 0, since E has not been 
bound at this time. Note that F[K](E):= SUBST(K,'J,'(COEFF(E,X,J))) would return 
the desired result as would F(K,E):=COEFF(E,X,K). Thus the user should be clear 
about the distinction between subscripted functions (a type of array) and ordinary 
functions. Also a subscripted function should not be redefined without KILL'ing or 
REMARRAY'ing it first; otherwise the elements which have already been stored 
will be used. 

The ARRAYS[[]] list (see 2.6.2) also includes subscripted functions. 

The function ARRAYINFO (see 8.1.1) may also be used on subscripted 
functions. 

(Cl) T[N](X):=RATSIMP(2*X*T[N-l](X)-T[N-2](X))t 

This generates the Chebyshev polynomials. 

<C2) T[0](X):=li 
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(C3) T[1](X): = X1 
(C4) T[4J(Y); 



4 2 



(D4> a v _ u v A i 



(C5) G[N](X):=SUM(EV(X),I,N r N+2)f 
<C6) H(N.X):=SUM(EV(X).I,N,N+2)i 

(C7) G[2](I-2); 

2 

(D7) 3 I 

(C8) H(2.I-2); 

(08) 29 

The following illustrates a definition for the Legendre polynomials. 
<C9) P[N](X): S RATSIMP(l/(2 A N*N!)*DIFF((r2-irN,X,N))t 
(CIO) 0(N f X):=RATSIHP(l/(2-N«N!)*0IFF((X-2-irN,X.N))t 

(Cll) P[2]; 

2 
3 X - 1 
< D11 > LAMBDA(CX], ) 

2 

(C12) P[2](Y-H); 

2 

3 (Y ♦ 1) - 1 
(012) 

2 

(C13) 0(2. Y*l); 

2 

3 Y ♦ 6 Y ♦ 2 
(D13) 

2 

(CI4) P[2](5); 

(014) 37 
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(C15) Q(2,5); 

5 

attempt to differentiate wrt a number 



[2.6.5] Additional Information About Functions 



In order to pass a function as an argument to another function you need only 
give its name in the argument list of the call. It may then be used in the called 
function by following the name of the corresponding formal parameter with a 
parenthesized list of arguments. Subscripted functions (see 2.6,4) are passed by 
giving the name followed by the subscripts in brackets. Arrays can be passed by 
giving the name of the array in the argument list and they can be referenced by 
subscripting the corresponding formal parameter. 

When passing names of functions or arrays one must take care that there is 
no atomic variable with the same name which is bound because then that value 
rather than the name will be passed. In this case the name should be preceded 
by a ' (see 3.2) to prevent it from being evaluated. 

In order to assign to a formal parameter of a function so that the 
corresponding actual parameter gets changed (and remains changed) when the 
function is exited, then the :: operator rather than the : operator should be used. 

(C7) F[I,0](X f Y):=X-I ♦ YM; 

I J 

(07) F (X, Y) := X ♦ Y 

I. J 

(C8) G(FUN,ARG1,ARG2):=PRINT(FUN," APPLIED TO \ARG1," AND \ 
ARG2," IS ",FUN(ARGl,ARG2))t 

(C9) G(F[2,1].SIN(%PI),2*A); 

2 

LAMBDA([X,Y] t Y+X ) APPLIED TO AND 2 A IS 2 A 

(D9) 2 A 
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2.7 Lists 



Lists are ordered sets of elements which can be any MACSYMA expressions. 
They are written enclosed in brackets with elements separated by commas. If the 
value of a variable is a list, its elements may be obtained or assigned to by 
subscripting as with arrays. In certain cases lists are treated like vectors (row or 
column matrices), (see 2.8) Lists are sometimes used as arguments to 
MACSYMA functions (e.g. MATRIX, SOLVE, etc.). Chapter 8 describes 
functions for many list operations such as deleting elements, selecting an element, 
reversing a list, etc. 

(CI) [X~2,Y/3.-2]S 

(C2) X[i>X; 

3 
(02) X 

<C3) O.D1.D2]; 

2 Y 3 

< 03 > [A [X . - -2] , X ] 



3 



2.8 Matrices 



A matrix is a 2-dimensional ordered set of elements. It is represented 
internally using a list of lists all of the same length which stand for the rows of 
the matrix. Matrices may be constructed by using the function MATRIX whose 
arguments are lists representing the rows of the matrix. (The functions 
ENTERMATRIX and GENMATRIX may also be used to construct a matrix (see 
6.4).) 

The operators ♦ , - , * , and / may be used between two matrices and take 
effect elementwise. (A matrix minus itself gives the zero matrix of the same 
size.) They may also be used between a scalar and a matrix and the scalar will be 
operated on with each element of the matrix. 1 



1. In MACSYMA a scaiar is an expression free of lists, matrices, and any atoms 
declared NONSCALAR. 
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Matrix multiplication is signified by using the dot operator (non-cornmutative 
product). Raising a matrix to a power (multiplying it by itself) is accomplished by 
use of the ~^ operator. That is, M.M is equivalent to M~~2. The inverse of a 
matrix may be obtained by using a negative exponent, i.e. M^~-l. 

If the switch LISTARITHfTRUE] is TRUE then 

1) Lists will behave arithmetically: they can be added to one 
another, etc. 

2) In matrix operations they can be used as row or column vectors 
and will be converted to such when necessary. 

An element of a matrix may be referenced by subscripting the matrix as with 
arrays but the same name should not be used to stand for both a matrix and an 
array. 

There are many functions for operating on matrices as well as many options 
which can be set to give the user much flexibility and control over matrix 
operations (these are described in sec. 6,4). If a matrix is too wide to be 

dier%lo\/Ofl sll d An/>a it !e Hi 6*\l ^M^*t *»^l« •■*»»» t\v *»«Ji ■»»•% #*•> «»e a li@i #»< lict#» 
■ s^riajfSu en at wiiv€| iv i9 \ii 9f^i ajr wv« v*wiuiiiii tjj vwiuiim wi o9 a nSi wi ii5i _ 



119. 



(CI) M:MATRIX([A,03,[B,1]); 

C A ] 

(01) [ ] 

C B 1 ] 

<C2) M[l,l]*%; 

[ 2 3 

(02) [A ] 

C ] 
[ABA] 

(C3) M«H; 

C 2 3 

[A ] 

(03) [ ] 

C 2 ] 

C B 13 

(C4) M.M; 
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(04) 

(C5) D2-D4+1; 

(05) 

(C6) M~-l; 
OIVISION BY 



f 2 ] 

[A ] 

t 3 

[ A B ♦ B 1 ] 



t 1 1 3 

[ 3 

C I - B A3 



<C7) rr~-i : 



(07) 



(C8) [X,Y3.H; 
(08) 



B 

- - 1 
A 



[ B Y ♦ A X Y3 



2.9 Equations 



An equat.on is formed in MACSYMA simply by using an equal sign between 

n?L^H eXP H eS ^ n ,\ EqUatl0nS may be added » ^btracted'and they may be 
MArqYMA 0r ^ 6y a Z y ex P ression - Th «y may be operated on just as an 
MACSYMA expression can be and may serve as arguments to functions 

(Cl) X+1=Y~2* 



(C?) X-1=2*Y+1* 
(C3) 01+D2; 
(D3) 



H:Y ♦ 2 Y ♦ 1 
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(C4) Dl/Y; 

X + 1 
(DA) ----- = Y 

Y 



Y 1 

X ♦ 1 Y 



(C5) l/%; 
(D5) 

[2.10] IF Statement 



The IF statement is used for conditional execution. The syntax is 

IF condition THEN expression! ELSE expres$ion2. 

The result of an IF statement is expression! if condition is true and expression2 if 
it is false, expression! and expression2 are any MACSYMA expressions (including 
nested IF statements), and condition is an expression which evaluates to TRUE or 
FALSE and is composed of relational and logical operators which are as follows: 



Operator name 


Symbol 


Type 


greater than 


> 


relational infix 


equal to 


= , EQUAL 


H N 


not equal to 


* 


n n 


less than 


< 


ft N 


greater than 


>s= 




or equal to 




» M 


less than 


<= 




or equal to 




N N 


and 


AND 


logical infix 


or 


OR 


M M 


not 


NOT 


logical prefix 



The relational operators all have equal priorities which are less than the 
priorities of the arithmetic operators and greater than that of the logical 
operators. The priority of NOT is greater than that of AND which is greater than 
that of OR. The difference between "=** and EQUAL is discussed in sec. 
7.1. 
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If the ELSE clause is omitted, this will be the same as if ELSE FALSE were 
specified In order to have several expressions evaluated after the THEN or ELSE 
clauses, the expressions may be enclosed in a compound statement (see 
2.11) but care should be taken to return the desired value. The switch 
PREDERROR[TRUE] determines the action taken if a clause is not universally true 
or universally false (see 7.1). 

(CI) FIB[N]:= IF N=l OR N=2 THEN 1 
ELSE FIB[N-l]+FIB[N-2]t 

<C2) FIB[1]+FIB[2]; 

(02) 2 
<C3) FIB[3]; 

(03) 2 
<C4) FIB[5]; 

(04) 5 

(C5) ETA(MU.NU):= IF MU=NU THEN NU 

ELSE IF NU>NU THEN HU-IW 
ELSE MU+NUt 

(C6) ETA(5,6); 

(06) 11 

(C7) ETA(ETA(7.7).ETA(1,2»; 

(07) 4 

(C8) IF NOT 5>=2 ANO 6<=5 OR 4+l>3 THEN A ELSE B; 

(08) A 

[2. II] Compound Statements 



In order to execute a sequence of statements in a context where a single 
statement is permitted then the user may group these statements into a 
compound statement by separating them with commas and enclosing the whole 
group in parentheses. The value of a compound statement is the value of the last 
statement in the group. 
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Compound statements are also useful for grouping together a sequence of 
related calculations when a computation cannot easily be expressed in a single 
MACSYMA statement. 

(Cl) IF X=Y THEN (X:X+1, Y:Y-1) 

ELSE (S:0, FOR 1:1 THRU X DO (S:S+F(I), Y:Y-G(Y)))t 



[2. 1 2] Program Blocks 

Blocks in MACSYMA are somewhat analogous to subroutines in FORTRAN or 
procedures in ALGOL or PL/I. Blocks are like compound statements but also 
enable the user to tag statements within the block and to assign "dummy" 
variables to values which are local to the block. The syntax is: 

BLOCKtfW, ... vk], statement 1,..., statement]) 

where the vi are atomic variables which are locai to the BLOCK and the 
statements are any MACSYMA expressions. If no variables are to be made local 
then the list may be omitted. 

A block uses these local variables to. avoid conflict with variables having the 
same names used outside of the block (i.e. global to the block). In this case, upon 
entry to the block, the global values are saved onto a stack and are inaccessible 
while the block is being executed The local variables then are unbound so that 
they evatuate to themselves. They may be bound to arbitrary values within the 
block but when the block is exited the saved values are restored to these 
variables. The values created in the block for these local variables are lost. 
Where a variable is used within a block and is not in the list of local variables for 
that block it will be the same as the variable used outside of the block. 

In order to save and restore other local properties besides VALUE, namely 
ARRAY (except for complete arrays - (see 10.8)), FUNCTION, 
DEPENDENCIES, ATVALUE, MATCHDECLARE, ATOMGRAD, CONSTANT, and 
NONSCALAR 1 (see 8.1), the function LOCAL should be used inside of the 
block with arguments being the names of the variables (see 10.6). 

The value of the block is the value of the last statement or the value of the 

1. All of these properties except for FUNCTION are related more closely to the 
use of the name as a variable rather than as a function 
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argument to the function RETURN which may be used to exit explicitly from the 
block The function GO may be used to transfer control to the statement of the 
block that is tagged with the argument to GO. To tag a statement, precede it by 
an atomic argument as another statement in the BLOCK. For examole 
BL0CK([X],X:1,L00P,X:X + 1 > ...,G0(L00P),.). The argument to GO may be any 

rnK^,?Trp^^^vu Va, i; ateS t0 a tag * For exam ? ,e G0(,F X>Y THEN p LACEl ELSE 
COMPUTEPLACE(X)). One cannot use GO to transfer to a tag in a BLOCK other 
than the one containing the GO. 

Blocks typically appear on the right side of a function definition but can be 
used in other places as well. 

(Cl) HESSIAN(F): S BLOCK([OFXX,DFXY f DFXZ f DFYY,DFYZ,DFZZ] t 
DFXX:DIFF(F,X,2),DFXY:DIFF(F.X,l f Y,l). 
DFXZ:DIFF(F.X.1,Z,1),DFYY:DIFF(F,Y,2). 
DFYZ:DIFF(F,Y,l,Z,l) t DFZZ:DIFF<F,Z,2), 

DE1ERMINANT(MATRIX([DFXX,DFXY,DFXZ],[DFXY.DFYY.DFYZJ 
[DFXZ,DFYZ,DFZZ])))t 

<C2) HESSIAN(X A 3-3*A*X*Y*Z*Y*3); 

* 2 3 2 3 

<02) -54 A X Y Z - 54 A Y -MA X 

<C3) SUBST(l,Z i QUOTIENT(%.-54*A A 2)); 

3 3 

(03) X ♦ A Y X ♦ Y 

The above example computes the Hessian of a cubic curve (the Folium of 
Descartes) which turns out to be invariant under this transformation, i.e. the result 
is of the same form. 

The example below illustrates the saving and restoring of values described at 
the beginning of this section. 

<C4) F(X):*BLOCK<[YL LOCAL(A), Y:4, A[Y]:X, DISPLAY(A[Y]))t 
<C5) Y:2t 

(C6) A[Y-»-2]:0i 
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(C7) F(9); 



A = 9 
4 

(07) DONE 

<C8) A[Y+2]; 

(08) 

If LOCAL(A) had not been used, the value on line D8 would have been 9. 
[2. 1 3] The DO Statement 

The DO statement is used for performing iteration. Due to its great 
generality the DO statement will be described in two parts. First the usual form 
will be given which is analogous to that used in several other programming 
languages (FORTRAN, ALGOL, PL/I, etc.); then the other features will be 
mentioned. 

[2.13.1] Commonly Used Forms 

There are three variants of this form that differ only in their terminating 
conditions. They are: 

(a) FOR variable : initial-value STEP increment 

THRU limit DO body 

(b) FOR variable : initial-value STEP increment 
WHILE condition DO body 

(c) FOR variable ; initial-value STEP increment 

UNLESS condition DO body 

(Alternatively, the STEP may be given after the termination condition or limit. ) 
The initial -value, increment, limit, and body can be any expressions. To 
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isee 2 tuVVZ^^X^X* C8n be made into a com P ound Element 
(see 2.1 1) or a BLOCK (see 2.12). The condition is as in the IF statement If th* 
mcrement is 1 then "STEP 1" may be omitted. statement. If the 

The execution of the DO statement proceeds by first assigning the initial- 
value lo the variable (henceforth called the control-variable). Then: <T) "the 

IT™ mills tjRur d i sr " mit j? a ™ Ru speci,ication - ° r «« Condition 

of the UNLESS is TRUE, or if the cond,t,on of the WHILE is FALSE then the DO 
termites (2) The body is evaluated. (3) The increment is added to the control 
variable The process from (1) to (3) is performed repeatedly untT the 

:zT c :::^zv aiisfi r d °r may ais ° give ~ w " te - inati °" <** 

m which case the DO terminates when any of them is satisfied. 

th« !" 7 e 7iK tHe THRU t6St iS S8tiS,ied When the "ntrol-variable is greater than 
he „nvt if the mcrement was non-negative, or when the control-variable is ess 

3 /,m " " the '"~»" was negative. The increment and limit may be non- 
uZ« th eXPreSS '° nS , "•, '° ng " tWs inequalit y can be determined. However, 

Ume he nnTr' : SknpW " t0 be " eeative (ie - is a "^tive number) at the 
hme the DO statement .s input, MACSYMA assumes it will be positive when the 
DO ,s executed. If ,t ,s not positive, then the DO may not terminate properly 

f im ^K te th , a !u lh f " m '\[ ncreme ^ a^ termination condition are evaluated each 

esul SI |0 °P- Thus if any of these involve much computation, and yield a 

result that does not change during all the executions of the body, then it is more 

the Do f ™. a Vanable t0 thCir V3lUe Pri0r t0 the °° and usa «. variable "in 

stat e me^t V tnVAcTYM y A rel r ed * a , D ° $tatement ' S the atom °° NE ' as ev ^ry 
2 12?^™ h. , VlT a Value ' However ' tne ,unction RETURN (see 
2.12) may be used mside the body to exit the DO prematurely and give it anv 
desired value. Note however that a RETURN within a DO that ^ in a BLOCK 
w-ll exit only the DO and not the BLOCK. Note also that the GO funct on may not 
be used to exit from a DO into a surrounding BLOCK. * 

used T vv? t h C n °M, lr °« Va , riab ',t iS a ! W3yS l0Cal t0 the °° and thus a "Y va "able may be 
used without affecting .he value of a variable with the same name outside of the 
DO. The control-variable is unbound after the 00 terminates. 

<C1> FOR A: -3 THRU 26 STEP 7 00 LDISPLAY(A)! 
(El) A = -3 



(E?) A = 4 

<E3) A = 11 

<E4) A = 18 
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(E5) A = 25 

The function LDISPLAY generates intermediate labels; DISPLAY does not. 



(C6) 


S:0t 


(C7) 


FOR 1:1 WHILE I<=10 DO S:S+I; 


(D7) 


DONE 


(C8) 


S; 


(08) 


55 



Note that the condition in 07 is equivalent to UNLESS I > 10 and also THRU 10 

(C9) SERIES: It 

(CIO) TERM:EXP(SIN(X))t 

(Cll) FOR P:l UNLESS P>7 DO 

(TERM:DIFF(TERM,X)/P, 

SERIES : SERIES+SUBSTC X*0 , TERH )*X*P )§ 
(C12) SERIES; 

I O 9 «t 2 

(D12) X X X X X 

+ — ♦ X ♦ 1 

96 240 15 8 2 

which gives 8 terms of the Taylor series for e 8,r * x '. 

(C13) POLY:0t 

(C14) FOR 1:1 THRU 5 DO 

FOR J:I STEP -1 THRU 1 DO 
POLY: POLY* I*X*0I 

(C15) POLY; 

5 4 3 2 
(015) 5X ♦ 9 X + 12 X + 14 X ♦ 15 X 

(C16) GUESS:-3.0S 

(C17) FOR 1:1 THRU 10 DO (GUESS:SUBST(GUESS,X, .5*(X+10/X)), 
IF ABS(GUESS A 2-10)<. 00005 THEN RETURN(GUESS)); 

(D17) - 3.1622807 
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This example computes the negative square root of 10 using the Newton- 
Kaphson iteration a maximum of 10 times. Had the convergence criterion not been 
met the value returned would have been "DONE". 

[2. 1 3.2] Additional Forms of the DO Statement 

Instead of always adding a quantity to the control-variable one may 
somet.mes wish to change it in some other way for each iteration. In this case 
one may use NEXT expression" instead of "STEP increment". This will cause the 
control- variable to be set to the result of evaluating expression each time 
through the loop. 

(CI) FOR COUNT: 2 NEXT 3*COUNT THRU 20 
00 DISPLAY(COUNT)t 

COUNT = 2 
COUNT = 6 
COUNT = 18 

As an alternative to FOR variable:value ...DO... the syntax FOR variable FROM 
value ...DO... may be used. This permits the "FROM value" to be placed after the 
step or next value or after the termination condition. If "FROM value". is omitted 
then 1 is used as the initial value. 

Sometimes one may be interested in performing an iteration where the 
control-variable is never actually used. It is thus permissible to give only the 
termination, conditions omitting the initialization and updating information as in the 
following example to compute the square-root of 5 using a poor initial guess. 

(Cl) X:1000 

(C2) THRU 10 WHILE X#0.0 DO X: .5*(X*5.0/X)I 
(C3) X; 

< 03 ) 2.236068 

• lf »™l des i red one ma y even omit the termination conditions entirely and just 
give DO body which will continue to evaluate the body indefinitely in this case 
the function RETURN (see 2.1 1) should be used to terminate execution of the DO. 
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(Cl) NEWTON(F, GUESS) :=BLOCK([NUHER,Y],LOCAL(DF),NUMER:TRUE, 
DEFINE(DF(X),DIFF(F(X),X)), 
DO (Y:DF( GUESS), IF Y=0.0 THEN ERROR( 

"DERIVATIVE AT", GUESS," IS ZERO"), 
GUESS : GUESS-F ( GUESS ) / Y , 
IF ABS(F(GUESS))<5.0E-6 THEN RE TURN (GUESS )))t 

(C2) SQR(X):=X*2-5.0t 

(C3) NEWTON (SQR. 1000); 

(D3) 2.236068 



(Note that RETURN, when executed, causes the current value of GUESS to be 
returned as the value of the DO. The BLOCK is exited and this value of the DO is 
returned as the value of the BLOCK because the DO is the last statement in the 
block.) 

One other form of the DO is available in MACSYMA. The syntax is: 
FOR variable IN list [end-tests] DO body 

The members of the list (see 2.7) are any expressions which will successively 
be assigned to the variable on each iteration of the body. The optional end-tests 
can be used to terminate execution of the DO; otherwise it will terminate when 
the list is exhausted or when a RETURN is executed in the body. (In fact, list may 
be any non-atomic expression, and successive parts are taken.) 

(Cl) FOR F IN [LOG, RHO, ATAN] DO LDISP(F(1.0))f 

(El) 

(E2) RHO(l) 

XPI 

(E3) 

4 

(C4) EV(E3,NUMER); 

(04) 0.78539816 
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[2.14] Syntax Extension 



It is possible to add new operators to MACSYMA (infix, prefix, postfix, unary, 
or matchfix with given precedences), to remove existing operators, or to redefine 
the precedence of existing operators. Details may be found in Appendix II. 
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3 What a Serious User Should Know 



Usually the user need not be concerned with the internal workings of 
MACSYMA, but some knowledge of the representation of expressions and of the 
way in which they are evaluated, simplified, and displayed should be acquired in 
order to use MACSYMA more easily, efficiently, and effectively. 



3.1 Representation 

After an expression is read by MACSYMA it is automatically translated (i.e. 
lexically scanned and parsed) to a LISP "internal" form. This is the form in which 
MACSYMA's programs deal with expressions. Initially the translated expression is 
in "general" form but certain functions convert this to other forms. 

(1) The general form represents non-atomic expressions as LISP lists whose 
first element is the main operator of the expression and whose remaining 
elements are the operands also represented in this form. Thus, after 

~ ... —,- . i-j ^_i:-n.. 1 — /pi I ie /DAT Q A\ /TIMFQ O 

simplification, Z*X+3/*t is represented essenuaily - a» \KuJb *■*«• ~ h, ,..*.. — - 
X)). F(X)-LOG(X) is represented as (PLUS (F X) (TIMES -1 (LOG X)». Any 
expression which MACSYMA deals with can be represented in this form. 

(2) Canonical Rational Expressions constitute a second kind of 
representation which is especially suitable for expanded polynomials and rational 
functions (as well as for partially factored polynomials and rational functions when 
RATFAC[FALSE] is set to TRUE, (see 6.5)). In this CRE form an ordering 
of variables (from most to least main) is assumed for each expression. 
Polynomials are represented recursively by a list consisting of the main variable 
followed by a series of pairs of expressions, one for each term of the polynomial. 
The first member of each pair is the exponent of the main variable in that term 
and the second member is the coefficient of that term which could be a number or 
a polynomial in another variable again represented in this form. Thus the principal 
part of the CRE form of 3*X"2-1 is (X 2 3 -1) and that of 2*X*Y+X-3 is (Y 1 
(X 1 2) (X 1 1 -3)) assuming Y is the main variable, and is (X 1 (Y 1 2 1) 
-3) assuming X is the main variable. "Main"-ness is usually determined by reverse 
alphabetical order. 

The "variables" of a CRE expression needn't be atomic. In fact any 



1. Ignoring the flags MACSYMA places on operators 
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subexpression whose main operator is not ♦ - * / or ~ with integer power will be 
considered a variable of the expression (in CRE form) in which it occurs. For 

rnBTrn ! c,nL V ?I ^ ^! e .i°' thS ex P ression X+SIN(X + 1) + 2*SQRT(X) + 1 are X, 
SQRT(X) and SIN(X + 1). If the user does not specify an ordering of variables bv 
using the RATVARS function (see 6.5) MACSYMA will choose an alphabeuc 



one 



In general, CRE s represent rational expressions, that is, ratios of polynomials 
where the numerator and denominator have no common factors, and the 
denominator is positive. The internal form is essentially a pair of polynomials (the 
numerator and denominator) preceded by the variable ordering list. 

If an expression to be displayed is in CRE form or if it contains any 
subexpressions in CRE form, the symbol /R/ will follow the line label. 

(3) An extended CRE form is used for the representation of Taylor series 
The notion of a rational expression is extended so that the exponents of the 
variables can be positive or negative rational numbers rather than just positive 
integers and the coefficients can themselves be rational expressions as described 
above in (2) rather than just polynomials. These are represented internally by a 
recursive polynomial form which is similar to and is a generalization of CRE form, 
but carries additional information such as the degree of truncation. 

As with CRE form, the symbol /T/ follows the line label of such expressions. 

(4) When RATFAC[FALSE] is TRUE,expressions are brought into partially 
Tactorcd form: numerator and denominator are relatively prime products of 
recursively constructed primitive polynomial kernels. Kernels at the same level 
w.thm numerator and denominator may not be relatively prime. In the future, 
kernels may be further specified to be square-free. 

(5) Another internal form is used to represent Poisson series. This 
specialized representation of trigonometric series is described in section 

D.O. 



3.2 Evaluation 



After MACSYMA parses a command line the expression is evaluated and 
simplified and the result is displayed Often the two-phase process of evaluation 
and simplification is referred to simply as -evaluation." In this section though, we 
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use the word "evaluation" to refer only to the evaluation stage proper and not to 
the simplification stage. 

MACSYMA expressions consist of numbers, variables, function calls, and 
operators. When an expression is read by MACSYMA the parsing program 
translates it into LISP preserving the order and the result is the value of the 
current C line. The evaluation phase proceeds by building up an expression which 
is similar in form to the input expression, but has certain substitutions. The 
evaluator is recursive, and calls itself on all sub-expressions. 

When the evaluator sees a name, it checks to see whether the name has a 
value assigned to it. If there is a value, that value is returned by the evaluator. If 
there is no value assigned to the name, the evaluator just returns the name itself. 
(For the means of assigning values to names refer to 2.4. For a description of the 
evaluation process as applied to subscripted names see 2.6.2). Note that 
problems could arise if a variable is bound to an expression containing an 
occurrence of that variable since each time the variable is evaluated, the entire 
expression is substituted for each occurrence of the variable. For example if Y 
has the value [X,Y,Z] and if the value of Y is evaluated the result is [X,[X,Y,Z],Z]. 

MACSYMA distinguishes between two types of functions - nouns and verbs. 
Most functions in the system, including all user-defined functions, are initially 
considered to be verb-type. Undefined functions and some system functions are 
considered to be noun-type. When the evaluator sees a function call, it evaluates 
the arguments to the function (unless that function is of a type which doesn't have 
its arguments evaluated, e.g. BATCH; for a list of such functions see Appendix VI). 
Then, if the function is verb-type, the evaluator applies the function to the 
evaluated arguments and returns the value of the function. For noun-type 
functions the evaluator returns an expression identical to the function call, except 
that the arguments are replaced by their evaluations. 

The user can explicitly declare a name to be noun-type by using the 
DECLARE function (see 8.1.1). ! For example, the function INTEGRATE 
normally tries to integrate its first argument. After the command 
DECLARE(INTEGRATE,NOUN) is given however, INTEGRATE will not perform the 
integration. Sometimes the user may give a verb function arguments which it is 
not equipped to deal with. In certain cases the verb function will return the noun 
form of itself. If this was because of some undefined functions in the expression, 



1. The noun-ness applies to both the function use and array use of the name. 
Note that nounifying a function name F doesn't affect occurrences of F that 
existed before F was nounified. 
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which the user defines at a later time, he can cause the noun-form to be re- 
evaluated at that time by giving the label of that line followed by the name of the 
unevaluated function separated with a comma as arguments of the function EV 
(see 6.1). For example: 

(CI) DIFF(X*F(X).X); 

d 
(0!) X (-- F(X)) ♦ F(X) 

dX 

(C2) F(X):=SIN(X)t 

(C3) EV(Dl.DIFF); 

(03) SIN(X) 4- X COS(X) 



Here we see that the expression returned by the evaluator is similar to the 
input expression. The basic difference is that names which have values are 
replaced by their values and verb-type function calls are replaced by the result 
of applying the function to its arguments. 

MACSYMA has several special operators which give the user some control 
over the evaluation process. The single-quote operator * has the effect of 
preventing evaluation. Thus an expression preceded by a single-quote evaluates 
to that expression. A special case is the evaluation of a function call where the 
name of the function is preceded by a quote as in 'F(X). In this instance the quote 
causes the function to be treated as though it were noun-type. 

To simply prevent evaluation of F(X) without converting F to a noun, use 
'<F(X)>. 

The quote-quote operator, ' ' , causes an extra evaluation to occur. It is best 
considered as a macro character. Inputting an expression preceded by a quote- 
quote has exactly the same effect as inputting the result of evaluating and 
simplifying the expression. In other words when an inputted expression contains a 
sub-expression which begins with a quote-quote that sub-expression is replaced 
in the input string by the result of evaluating and simplifying the expression 
following the quote-quote. This occurs at the time an expression is parsed. In 
the case of evaluating a function call with a " preceding the name of the function 
(i.e. "F(x) ), the " causes the function to be treated as if it were verb-type. 
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(CI) X; 


(01) 


(C2) X:3t 


(C3) X; 


(03) 


(C4) 'X; 


(04) 


(C5) F(X):=X*2; 


(D5) 


(C6) 'F(2); 


(06) 


(C7) EV(%.F); 


(07) 


/ *»Q \ * i IT I t\\ m 
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2 
F(X) := X 



F(2) 



(D8) P(2) 

(C9) "%; 

("atom means evaluate the atom's value) 

(09) 4 

(CIO) DECLARE( INTEGRATE, N0UN)$ 

(Cll) INTEGRATE* Y*2.Y); 

/ 
C 2 
(Oil) I Y OY 

] 
/ 
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(C12) "INTEGRATE(Y*2,Y); 

3 
Y 

(D12) 

3 

(C13) F<Y):=DIFF(Y*L0G(Y),Y,2); 

(013) F(Y) := DIFF(Y L06(Y), Y. 2) 

(C14) F(Y): = "<DIFF(Y*lOG(Y) t Y,2)); 

1 

(014) F(Y> :* - 

Y 

<C15) C14; 

1 

(015) F(Y) :x - 

Y 

(Notice that the input expression has been changed due to the use of f \) 

Referring to line (CI 4) above, suppose one wished to define the function F(Y) 
as DIFF(Y*LOG(Y),Y,l) within another function G(l) where the I in the definition of 
F(Y) is to be replaced by the argument to G when G is called. 

G(l):=BLOCK(...,F(Y):="(DIFF(Y*LOG(Y),Y,l)),..) will not do the job because the 
" operator will cause the differentiation to be carried out at parse time and thus 
either an error will result (if I is unbound) or the current global value of I will be 
used rather than the value of the argument to G when it is called. Omitting the " 
is also not desirable in this example because that would force the differentiation 
to be done each time F is called rather than at the time it is defined To remedy 
this one may use the command 

DEFINED function(argument$),body) 

whkh is like fundi on( arguments) :="body but causes the evaluation of body to 

°zcur at the time DEFINE is evaluated. Thus 

G(h^BLOCK(...,DEFINE(F(Y),DIFF(Y*LOG(Y),Y J l)),...) will work properly. DEFINE may 
also be used for subscripted functions. 



MACSYMA 39 



3.3 Simplification 



The simplifier takes the output of the evaluator and tries to make it smaller 
and more manageable, using some built-in algebra. Unless the user takes some 
special action (like setting the special variable SIMP to FALSE (see 6.1)), 
MACSYMA will never output an unsimplified expression. The simplifier re-orders 
expressions in order to obtain a standard form and the result is the value of the 
current D line. Thus A+B+C or C+A+B or C+B+A if input, will all result in the 
same internal form, (PLUS ABC) which displays as C + B + A . The simplifier also 
changes the SQRT function to exponentiation to the 1/2 power and removes the 
difference and quotient operators from the expression by converting X-Y to X+(- 
1)*Y andX/Y to X*Y _1 . 

Roughly speaking, the simplifier orders expressions on the basis of their 
subexpressions being ordered first. Variables are ordered alphabetically i.e., from 
A to Z. Constants (%E, 7.PI, XI and any atoms DECLAREd CONSTANT) come before 
variables and numbers come before constants. Finally, functions are ordered 
according to their arguments*, and according to their names in case their 
arguments are the same. Thus Y+2*A*X-7.PI would become (PLUS (TIMES -1 XPI) 
(TiMES 2 A X) Y». 

The user should be aware that the line between evaluation and simplification 
is not clear-cut. For instance, SIN is a noun-function. When the evaluator sees 
SIN(O), it returns SIN(O). However, the simplifier notices this special case and 
changes this expression to 0. So simplification will sometimes obscure the 
difference between noun and verb functions. 

[Mol] mentions these and many other matters dealing with simplification. 



1. Comparing first arguments first, second arguments second, etc. 
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4 Miscellaneous Hints and Facilities 



Care Should hft fair on in r»A» t..l. A - A — -^ ... ... 

i i _. "i „ — — *-■• »• w»se» A.. c r c mi expression containing X is re- 
evaluated since the value of •/. changes each time a new line is computed. This is 
shown in the following example. 



(Cl) (X+Yr3t 
<C2) DIFF(X.X); 

2 

< D2 > 3 (Y + X) 

<C3) Y:X~2*lt 

(C4> "C2; 

(04) 2 X 



.tsii ^ I'" 6 ^ 4 / h nl JSer L .? iay have lntended t0 re -e v a^ate C2 thinking that the X 
still referred to Dl while it actually referred to D3. Note the use of the • ' 
operator to re-evaluate a previous expression (see 3.2) 

The following interrupt characters typed wNle holding down the control key 
r h n a ' e J^! al Actions- They may be typed at any time— even in the middle of a 
command line— and take effect immediately. 

* (control-shift-N on some terminals) - enters top-level LISP after resetting 
all locally bound variables and breaking out of all functions. It is not possible to 

reTurMo MACS^A^ Ca,CU,ali ° n after a contro1 ^ but Wng (CONTINUE) will 

A - makes a breakpoint in MACSYMA and suspends the computation At this 
point the user is in a MACSYMA break loop. If a user function was being 
executed at the time of the break, its values may be printed or changed. Aside 
from this, it is almost like being at top-level MACSYMA. To exit and resume the 
computation type EXIT; (see 10.1). 

X - quits a computation started while in a control-A break without quitting 
the top-level computation. B 

] - (control-shift-M on some terminals) prints the time used so far in a 
computation (without interrupting it). 

K ~ reprints the current input line. This is useful when many rubouts have 
obscured the line (on hardcopy devices). 



MACSYMA 4 Miscellaneous Hints and Facilities 41 

Y - gets the last command string. 

L - clears the screen on display consoles and reprints the current line. 

W - stops printout at the console while the computation continues. ( If the 
user is connected to MACSYMA via the ARPA network, printout will not stop until 
the Arpanet buffer is emptied) The switch TTYOFF[FALSE] if set to TRUE also 
stops the printout. This is useful for temporarily turning off the display for 
functions which might generate a lot of printing like BATCH. Setting the switch to 
FALSE causes printing to be resumed. 

V - resumes printout at the console turned off by control-W. 

G - aborts a computation and returns control to top-level MACSYMA. This is 
like control-^ immediately followed by (CONTINUE) and is useful for breaking out 
of infinite loops or for terminating a computation prematurely. 

H - (backspace on some consoles) makes a "breakpoint" in MACSYMA, enters 
LISP, and prints the time used in the current computation. Control-H does not 
reset any values. Altmode (or Escape) P (for proceed) followed by a space will 
return to MACSYMA and resume the computation. Control-B also performs this 
function in NEWIO MACSYMA. 

D - causes garbage collection statistics to be printed out each time a garbage 
collection takes place [Mnl]. See Chapter 16. 

C - stops printout of garbage collection statistics turned on by control-D. 



Two of the many MACSYMA variables or options mentioned later on are of 
special interest and will be described here. 

(1) The value of LINEL gives the number of characters which are printed on a 
line. It is initially set by MACSYMA to the line length of the type of terminal 
being used (as far as is known) but may be reset at any time by the user. The 
user may have to reset it in DDT with :TCTYP as well. See [Lewi]. 

(2) If the variable SHOWTIME[FALSE] is TRUE then the computation time will 
be printed automatically with each output expression. 

Sometimes when a user gives a command line the message "... being loaded" 
will be printed. This means that a function being used in the command line and/or 
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the associated programs are not in the initially loaded MACSYMA but are being 
loaded in now y.a the dynamic loader. Infrequently used or inessential functions 
are not initially loaded into MACSYMA in an effort to save space. ,uncl,ons 

When in LISP typing (CONTINUE) or control-G will return to MACSYMA. 

c»t e 'T^ M \ Pr0V . ide ;: th * fadlity for the user l0 have an initialization file which 
fhin k n au t° mat,cal| y be,ore line <C1) is P rinled - « the user has a directory 
then the file should be named MACSYM (INIT). Otherwise he may place the file 
whose first file name is his login name and whose second file name is MACSYM on 
he d.rectory called (INIT). This file must be in the format for the LOADFILE 
function (see 0.4) Le it must contain LISP code. It may be created via the 
SAVE function (see 10.4) or by translating a BATCH file (see 10.8). 

th» l USCr Wi ? kn .°.« U ? P Sh0uld nole that ^^ding a name with a ? causes 
FAt « Lk P J?JL H^ atom l0 be inv ° ka * For example, ?FIXP(4.2); returns 
FALSE, where FIXP is the name of a LISP system function. 
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5 Predefined Constants and Functions 

5.1 Constants 

A number of common mathematical constants have special names in MACSYMA; 

%E - the base of the natural logarithms. 

7.PI - the transcendental number n. 

%l - the square root of -1. 

INF - real positive infinity. 

MINF - real minus infinity. 

INFINITY - complex infinity, an infinite magnitude of arbitrary phase angle.* 

TRUE - the Boolean constant, true. (T in LISP) 

FALSE - the Boolean constant, false. (NIL in LISP) 

5.2 Functions 



All of the functions mentioned below take one argument (shown as X) unless 
stated otherwise. The default values of MACSYMA variables which affect certain 
functions are given in brackets with the function 



1. The infinity symbols have meaning only for certain functions, for example, LIMIT, 
INTEGRATE, SUM. 
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5.2.1 Simple Functions 

ABSfW - absolute value of X 

ABSBOXCHARp] is the character used to draw absolute value signs 
around expressions which are more than a single line high. 



FLOATfexp; - converts integers, rational numbers and bigfloats in exp to floating 
point numbers. 



BFLOATYXJ - converts all numbers and functions of numbers to bigfloat numbers. 
Setting FPPREC[16] to N, sets the bigfloat precision to N digits. If 
FLOAT2BF[FALSE] is FALSE a warning message is printed when a floating 
point number is converted into a bigfloat number (since this may lead to loss 
of precision). 



ENTIERW - largest integer < X. 



SIGNUMfX) - if X<0 then -1 else if X>0 then 1 else 0. If X is not numeric then a 
simplified but equivalent form is returned For example, SIGNUM(-X) gives 
-SIGNUM<X). 



POLYSIGNW - same as SIGNUM but always returns a numerical result by looking 
at the numerical factor of the highest degree term in X. 



M\N(X1, X2, ...) yields the minimum of its arguments (or returns a simplified form if 
some of its arguments are non-numeric). 



MAX6Y/, X2, ...) yields the maximum of its arguments (or returns a simplified form 
if some of its arguments are non-numeric). 
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5.2.2 Miscellaneous Functions 



SQRTYXJ - the square root of X. It is represented internally by X^l/2). Also see 
ROOTSCONTRACT in section 6.1.1. 

RADPRODEXPAND[TRUE] - if TRUE will cause nth roots of factors of a 
product which are powers of n to be pulled outside of the radical, e.g. 
SQRT(16*X"2) will become 4*X only if RADPRODEXPAND is TRUE. 



ISQRTM - takes one integer arg and returns the "integer SQRT" of its absolute 
value. 



EXP(X) - the exponential function, it is represented internally as %E X.. 

DEMO!VRE[FALSE] - if TRUE will cause 7.E^[A+B*7.I] to become 
7.E^A*(COS(B)+7.l*SIN(B)) if B is free of 7.1. A and B are not expanded. 

7.EM0DE[TRUE] - when TRUE 7.E^[7.PI*7.I*X] will be simplified as follows: 
it will become COS(7.PI*X)+7.l*SIN<7.PI*X) if X is an integer or a multiple of 
1/2, 1/3, 1/4, or 1/6 and thus will simplify further. For other numerical X it 
will become 7.E^[7.PI*7.I*Y] where Y is X-2*k for some integer k such that 
ABS(Y)<1. If 7.EM0DE is FALSE no simplification of 7.E A [7.PI*7.I*X] will take 
place. 

7.ENUMER[FALSE] - when TRUE will cause 7.E to be converted into 
2.718... whenever NUMER is TRUE. The default is that this conversion will 
take place only if the exponent in y-E^X evaluates to a number. 



LOGW - the natural logarithm. 

LOGEXPAND[FALSE] - if TRUE will cause LOG(A/B) to become LOG(A)- 
LOG(B) and LOG(A*B) to become LOG(A)+LOG(B). This does not effect 
LOG(A B ) which always becomes B*LOG(A). 

LOGSIMP[TRUE] - if FALSE then no simplification of 7.E to a power 
containing LOG's is done. 
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LOGNUMER[FALSE] - if TRUE then negative floating point arguments to 
LOG will always be converted to their absolute value before the log is taken. 
If NUMER is also TRUE, then negative integer arguments to LOG will also be 
converted to their absolute value. 

The LOGCONTRACT command (see 6.1.1) "contracts- expressions containing 



PLOGW - the principal branch of the complex-valued natural logarithm with -7.PI 
< X < +%P| . 



GLOGW - the generalized logarithm, i.e. all branches. This is sometimes used by 
the definite integration package. 

BINOMIAL^ Y) - the binomial coefficient X*(X-1)*...*(X-Y+1)/Y!. If X and Y are 
integers, the binomial coefficient is actually computed. If Y or X-Y is an 
integer, the binomial coefficient is simplified to a polynomial. 

RANDOMS - returns a random integer between and X-l. If no argument is 
given then a random integer between -2 35 and 2 35 -l is returned. If X is 
FALSE then the random sequence is restarted from the beginning. 

Fm<X) mJ\* XlH Fibonacci number with TOW-Q, FIBUH1, and FIB(-NM- 
1> W1 >*FIB(N>. PREVFIB is FIB(X-l), the Fibonacci number preceding the last 
one computed. 

GENF *5J (X ' s, Y * Z) ' S lhe generalized factorial of X which is: X*(X-Z)*(X- 
G^ACwiafixn ^ f ° r inlegr8 * * ""TO*!)-* and 

GAMMAS - the gamma function. GAMMA(I)=(I-1)! for I a positive integer. 

GAMMALIM[ 1000000] controls simplification of the gamma function for 

integral and rational number arguments. If the absolute value of the argument 

s not greater than GAMMALIM, then simplification will occur. Note that the 
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FACTUM switch (see 2.5) controls simplification of the result of GAMMA of an 
integer argument as well. 



BETAfX, Y) - same as GAMMA(X)*GAMMA(Y)/GAMMA(X+Y) 

ERFW - the error function, whose derivative is: 2*EXP(-X^2)/SQRT(°/.PI). 

EULERfX* - gives the Xth Euler number for integer X. 

BERWXJ - gives the Xth Bernoulli number for integer X. 

ZEROBERN[TRUE] if set to FALSE excludes the zero BERNOULLI 
numbers. 

ZETAM - gives the Riemann zeta function for certain integer values of X. 

PSIW - derivative of LOG(GAMMA(X)). 

5.2.3 Trigonometric Functions 

This section outlines the way in which trigonometric functions are called in 
MACSYMA; for more information on the simplification of trigonometric functions and 
expressions, the user should read Section 2 of the MACSYMA Primer [Mo5]. 

Circular Functions 

SIN, COS, TAN, COT, SEC, CSC 

Inverse Circular Functions 

ASIN, ACQS , ATAN , ACOT , ASEC , ACSC 
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WAN2(Y,X) - yields the value of ATAN(Y/X) in the interval -7.PI to V.PI. 

Hyperbolic Functions 

SINH , COSH , TANH , COTH, SECH , CSCH 

Inverse Hyperbolic Functions 

ASINH , ACOSH ,ATANH , ACOTH , ASECH, ACSCH 

TRIGSIGNfTRUE] - if TRUE permits simplification of negative arguments to 
trigonometric functions. E.g., SINf-X) will become -SIN(X) only if TRIGSIGN is TRUE. 

EXP0NENT1ALIZE[FALSE] - if TRUE will cause all circular and hyperbolic 
functions to be converted to exponential form. 

LOGARC[FALSE] - if TRUE will cause the inverse circular and hyperbolic 
functions to be converted into logarithmic form 

Examples 
(CI) SIN(XPI/12)+TAN(XPI/6); 



XPI 1 
(01) SIN< — ) + 



(C2) EV(X,NUMER); 

(02) 0.8361693 

<C3) BETA(l/2,2/5); 

2 
SQRT(XPI) GAMMA(-) 

5 

(03) 

9 
GAMMA(--) 
10 

(C4) EV(X,NUHER); 

(04) 3.6790924 



12 SQRT(3) 
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(C5) DIFF(ATANH(SQRT(X)),X); 

1 
2 SQRT(X) (1 - X) 



(D5) 



(C6) SOLVE (X*2*10*5*X4-1); 
SOLUTION 



(E6) 

<E7) 

(D7) 

(C8) E7.NUMER; 
(D8) 

(C9) BFLOAT(E7); 
(09) 

(CIO) FPPREC:25t 

(Cll) SIN(.5B0); 
(Oil) 



X = - SQRT( 2499999999) - 50000 

X = SQRT( 2499999999) - 50000 

[E6 f E7] 

X « 2.9296875E-3 

X = - .99999997473787528-5 



.479425538604203000273287980 



The trigonometric simplification routines use declared information in some 
simple cases. Declarations about variables are used as follows, e.g. 



(C5) DECLARER, INTEGER, E. EVEN, 0, 000)t 
(C6) SIN(X ♦ (0*E ♦ l/2)*%PI)i 
(D6) COS(X) 

(C7) SIN(X + (0 + 1/2)*%PI); 



(07) 



- COS(X) 
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5.3 Complex Expressions 



A complex expression is specified in MACSYMA by adoW th* r ea ! -*,* ~# »u. 
X 2-4*X+13=0 are 2+3*%l and 2-3*XI. 

Examples 
(CI) (SQRT(-4)+SQRT<2.25)r2; 

2 
(01) (2 XI ♦ 1.5) 

(C2) EXPAND<X); 

6.0 XI - 1.75 

<C3) EXPAND(SQRT(2«XI)); 

(03) XI ♦ 1 

bv exoiL!n!\K imP,if i Ca l i0n e° f ^° d ^ t8 0f COmp,ex ex P^«ions can be effected 

o y m e n ndmg the . pr0duct »"P«»fl««on of quotients, roots, and other functions of 

complex expressions can usually be accomplished bv usine the RFAl papt 

IMAGPART, RECTFORM, P0LARF0RM, ABS, SSLSL^ ^3) ' 
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6 MACSYMA Functions and Variables 



Following is a list of all MACSYMA functions divided into functional classes. 
MACSYMA variables which affect the operation of some functions are described 
under the appropriate function with their default value in brackets. These are 
sometimes referred to as MACSYMA options. 



6. 1 General Purpose Functions 



6.1.1 Evaluation and Simplification Functions 



EVfexp, argl, ..., argn) is one of MACSYMA's most powerful and versatile 
commands. It evaluates the expression exp in the environment specified by 
the argi This is done in steps, as follows: 



(1) First the environment is set up by scanning the argi which may be as 
follows: 

SIMP causes exp to be simplified regardless of the setting of the switch 
SIMP which inhibits simplification if FALSE. 

NOEVAL suppresses the evaluation phase of EV (see step (4) below). 
This is useful in conjunction with the other switches and in causing exp to be 
resimplified without being reevaluated. 

EVAL causes an extra post-evaluation of exp to occur. (See step (5) 
below.) 

INFEVAL leads to an "infinite evaluation" mode. EV repeatedly evaluates 
an expression until it stops changing. To prevent a variable, say X, from 
being evaluated away in this mode, simply include X='X as an argument to EV. 
Of course expressions such as EV(X,X=X+1, INFEVAL); will generate an infinite 
loop. CAVEAT EVALUATOR. 

EXPAND causes expansion. 
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u*ir PAND ^'^ causes expansion, setting the values of MAXPOSEX and 
MAXNEGEX to m and n respectively, (see the EXPAND function below) 

DETOUT causes anv matrix inverses rompi •**<"* •« *»xn ♦« u*»« e #u~:„ 

determinant kept outside of the inverse rather than dividing through each 
element. 

DIFF causes all differentiations indicated in exp to be performed (see 
the DIFF function below.) 

DERIVLIST( var/,...,var*) causes only differentiations with respect to the 
indicated variables. 

FLOAT causes non-integral rational numbers to be converted to floating 
point. 

NUMER causes some mathematical functions (including exponentiation) 
with numerical arguments to be evaluated in floating point (see 5.2.1). It 
causes variables in exp wNch have been given numervals (see 8.1.2) to 
be replaced by their values. It also sets the FLOAT switch on. 

PREO causes predicates (expressions which evaluate to TRUE or FALSE) 
to be evaluated. 

NOUNS converts all nouns occurring in exp to verbs. 

E where E is an atom declared to be an EVFLAG (see 8.1.1) causes 
E to be bound to TRUE during the evaluation of exp. 

^.expression (or alternatively ^expression) causes V to be bound to the 
value of expression during the evaluation of exp. Note that if V is a 
MACSYMA option, then expression is used for its value during the evaluation 
of exp. If more than one argument to EV is of this type then the binding is 
done in parallel. If V is a non-atomic expression then a substitution rather 
than a binding is performed 

E where E is a function name declared to be an EVFUN (see 8.1) 
causes E to be applied to exp. 

Any other function names (e.g. SUM) cause evaluation of occurrences of 
those names in exp as though they were verbs (see 3.2). 
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In addition a function occurring in exp (say F(args)) may be defined locally 
for the purpose of this evaluation of exp by giving F(args):=body as an 
argument to EV. 

If an atom not mentioned above or a subscripted variable or subscripted 
expression was given as an argument, it is evaluated and if the result is an 
equation or assignment then the indicated binding or substitution is performed. 
If the result is a list then the members of the list are treated as if they were 
additional arguments given to EV. This permits a list of equations to be given 
(e.g. [X=l, Y=A**2] ) or a list of names of equations (e.g. [E1,E2] where El 
and E2 are equations) such as that returned by SOLVE, (see 6.3) 

The argi of EV usually may be given in any order but since they are 
picked up left to right the order may influence the result. This is strictly true 
of substitution equations which are handled in sequence, left to right, and 
EVFUNS which are composed, e.g. EV(exp,RATSIMP,RECTFORM) is handled as 
RECTFORM(RATSIMP(exp». The SIMP, NUMER, FLOAT, PRED, and INFEVAL 
switches may also be set locally in a block, or globally at the "top lever in 
MACSYMA so that they will remain in effect until being reset. Setting 
INFEVAL:TRUE locally will cause all evaluations occurring via explicit calls to 
EV to be done "infinitely . 

If exp is in CRE form (see 3.1) then EV will return a result in CRE form 
provided the NUMER and FLOAT switches are both FALSE. 

(2) During step (1), a list is made of the non-subscripted variables 
appearing on the left side of equations in the argi or in the value of some argi 
if the value is an equation. The variables (including subscripted variables) in 
the expression exp are replaced by their global values, except for those 
appearing in this list. Usually, exp is just a label or % (as in (C2) below), so 
this step simply retrieves the expression named by the label, so that EV may 
work on it. 



(3) If any substitutions are indicated by the argi, they are carried out 



now. 



(4) The resulting expression is then re-evaluated (unless one of the argi 
was NOEVAL) and simplified according the the argi. Note that any function 
calls in exp will be carried out after the variables in it are evaluated and that 
EV(F(X)) thus may behave like F(EV(X)). 

(5) If one of the argi was EVAL, steps (3) and (4) are repeated. 
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Examples 

(CI) SIN(X)+C0S(Y)+(W*1)**2+'DIFF(SIN(W),W); 

d 2 

(01) COS(Y) ♦ SIN(X) + --SIN(W) ♦ (W + 1)' 

dW 
(CZ) EV(%, SIN, EXPAND, DIFF,X=2,Y=1); 

2 

(02) COS(W) ♦ V ♦ 2 W ♦ C0S(1) + 1.90929742 

An alternate "top level" syntax has been provided for EV, whereby one 
may just type in its arguments, without the EV(). That is, one may write 
simply exp,argl,... t argn. (This is not permitted as part of another expression 
i.e. in functions, blocks, etc.). exp,RESCAN te equivalent to EV(exp). 

(C4) X+Y,X:A+Y,Y:2; 

(04) Y + A + 2 

(Notice the parallel binding process) 

(C5) 2*X-3*Y=3i 

(C6) -3*X+2*Ys-4t 

(C7) SOLVE([D5,D6J); 
solution 

1 
(E7) y a . . 

5 
6 
(E8) X=- 

5 

<°8) [E7, E8] 

(C9) D6.D8; 

(09) - 4 s . 4 

(CIO) X+l/X > GAMHA(l/2); 

1 
< D10 > X + - > SQRT(XPI) 

X 
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(Cll) %,NUMER,X=l/2; 

(Dll) 2-5 > 1.7724539 

(C12) '/..PRED; 

(012) TRUE 



UNKNOWNfexp; returns TRUE iff exp contains an operator or function not known 
to the built-in simplifies 

EXPANDfexp) causes products of sums and exponentiated sums to be multiplied 
out, numerators of rational expressions which are sums to be split into their 
respective terms, and multiplication (commutative and non-commutative) to be 
distributed over addition at all levels of exp. For polynomials one may wish 
use RATEXPAND which uses a more efficient algorithm (see below). 

Terms in exp whose exponent is less than MAXNEGEX[1000] or greater 
than MAXPOSEX[1000] will not be EXPANDed. However, 

EXPAND( exp,p,n) expands exp, using p for MAXPOSEX and n for 
MAXNEGEX. This helps the user control how much and what kinds of 
expansion are to take place. 

EXP0N[0] - the exponent of the largest negative power which is 
automatically expanded (independent of calls to EXPAND). For example if 
EXPON is 4 then (X+l)**(-5) will not be automatically expanded. 

EXP0P[0] - the highest positive exponent which is automatically 
expanded. Thus (X+l)**3, when typed, will be automatically expanded only if 
EXPOP is greater than or equal to 3. If it is desired to have (X+l)**n 
expanded where n is greater than EXPOP then executing EXPAND((X+l)**n) 
will work only if MAXPOSEX is not less than n. 

(Cl) (l/(X+Y)**4-3/(Y+Z)**3)**2; 

1 3 2 

(01) ( ) 

4 3 

(Y ♦ X) (Z + Y) 
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(C2) EXPAND(%,2,0); 

6 9 l 

(02) _. A * 

-*■ -------- + -_-_»««.. 

4 3 6 8 

(Y ♦ X) (Z ♦ Y) (Z ♦ Y) <Y ♦ X) 

<C3) EXPAND(A.(B*C.(D+E)+F)); 



(D3) A^ + A.C.E + A.C.D + A. 



B 



2™tW eXP S *u P by "•""Wng out products of sums and 

cZ.Z* h S T* , Combm,n S fractio " s °ver a common denominator, 

^hTn i^H %f eateSt C ? m T divls0r 0f the nu ^ator and denominator 
then splitting the numerator (if a sum) into its respective terms divided by 

, l~ n u r ,? JS iS accom P ,ished ^ converting exp to CRE form (see 
c*. I J and then back to general form 

•vn.^ 1 ? a ^ N, S rALSE1 * " TRUE wi " MUse CRE expressions to be fully 

,7?t I *™£ n l y ,r co r: ,ed back to generai ,o "" ° r *•!**•«. wni; 

below) Y * PUt int ° a recur8ive '°"«- <«e RATSIMP 

t e r m = A J?K N ° MD,V, ? E[TRUE] - " FALSE wi " st °P the s P«t«"6 up of the 
terms of the numerator of RATEXPANDed expressions from occurring 

fro m K hZ FLO r TIF 1 AL ! E] !! Sel t0 TRUE wi " P revent «**"* P<>i"t ™mbers 
to CTE form expressions which contain them are converted 

tak^hfjf 1 " FALSE Wi " Pr6Vent the peaiest common *«™ ««»" being 
IoAh 7k T^T' "! are c °" v erted to CRE form. This will sometimes 
speed the calculat.cn if gcds are not required (cf. the function GCD in 

(Cl) RATEXPAND((2«X-3»Y)**3); 

3 2 2 3 

(Dl) -27 V +54XY -36X Y ♦ 8 X 

(C2) (X-I)/(X+1)*»2+1/(X-1); 
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X - 1 1 

(02) ♦ 

2 X - 1 
(X ♦ 1) 

(C3) EXPAND(02); 

X 1 1 

(03) ♦ 

2 2 X - 1 

X ♦ 2 X ♦ 1 X ♦ 2 X ♦ 1 

(C4) RATEXPAN0(D2); 

2 
2 X 2 

(04) --------------- + --------------- 

3 2 3 2 

X+X-X-l X ♦ X - X - 1 



RATSIMPfexpyl "rationally'* simplifies (similar to RATEXPAND) the expression exp 
and all of its subexpressions including the arguments to non-rational functions. 
The result is returned as the quotient of two polynomials in a recursive form, 
i.e. the coefficients of the main variable are polynomials in the other 
variables; Variables may, as in RATEXPAND, include non-rational functions 
(e.g. SIN(X**2+1) ) but with RATSIMP, the arguments to non-rational functions 
are rationally simplified. Note that RATSIMP is affected by some of the 
variables which affect RATEXPAND. 

RATSIMPEXPONS[FALSE] - if TRUE will cause exponents of expressions 
to be RATSIMPed automatically during simplification. 



Rkl%MP(exp,vl t ... t vn) enables rational simplification with the specification of 
variable ordering as in RATVARS. 
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(CI) SIN(X/(X*2+X))=XE A ((LOG(X)M)**2-LOG(X)»*2); 



2 2 

X - LOG (X) ♦ (LOG(X) ♦ 1) 

(Dl) SIN(---^--) = XE 

2 
X + X 

(C2) RATSIMP(X); 

1 2 

(°2) SIN( ) = XE X 

X ♦ 1 

(C3) ((X-l).Mt(3/2)-(X+l)*S0RT(X-l))/SQRT((X-l)*(X*l)); 

3/2 
(X - 1) - SQRT(X - 1) (X ♦ 1) 
(D3) 

SQRT(X - 1) SQRT(X ♦ 1) 

(C4) RATSIHP(X); 

2 
(D4) 

SQRT(X ♦ 1) 



(C5) X**(A+1/A),*ATSIMPEXP0NS:TRUE; 

2 
A ♦ 1 



A 
(D5) X 



RADCANfexp,) simplifies exp, which can contain logs, exponentials, and radicals, by 
converting it into a form which is canonical over a large class of expressions 
ond a given ordering of variables; that is, all functionally equivalent forms are 
capped into a unique form. For a somewhat larger class of expressions, 
RADCAN produces a regular form [Fa2J Two equivalent expressions in this 
class will not necessarily have the same appearance, but their difference will 
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be simplified by RADCAN to zero. For some expressions RADCAN can be 
quite time consuming. This is the cost of exploring certain relationships 
among the components of the expression for simplifications based on factoring 
and partial-fraction expansions of exponents. 

RADPRODEXPAND[TRUE] when set to FALSE will inhibit certain 
transformations: RADCAN<SQRT<1-X)> will remain SQRT(l-X) and will not 
become XI SQRT(X-l). RADCAN(SQRT(x2-2*X+l)) will remain SQRT<x2-2*X ♦ 
1) and will not be transformed to X-l. 

(CI) (L06(X««2*X)-L0G(X))**A/L06(X+l)««(A/2); 

2 A 

(L06(X ♦ X) - LOG(X)) 
(01) 

A/2 
L0G(X ♦ 1) 

(C2) RADCAN(X); 

A/2 
(02) L06(X * 1) 

(C3) LOG(A^(2*X)+2*A**X+l)/LOG(A**X+l); 

2 X X 
L0G(A ♦ 2 A ♦ 1) 
(D3) 

X 
L06(A ♦ 1) 

(C4) RA0CAN(%); 

(04) 2 

(C5) (XE«*X-l)/(XE«*(X/2)+l); 

X 
XE - 1 

(05) 

X/2 
%E ♦ 1 

(C6) RADCAN(X); 
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X/2 






COMBINEfexp; simplifies the sum exp by combining terms with the same 
denominator into a single term. 



MULTTHRUfexp) multiplies a factor (which should be a sum) of exp by the other 
factors of exp. That is exp is fl*f2*...*fn where at least one factor, say fi, is 
a sum of terms. Each term in that sum is multiplied by the other factors in 
the product. (Namely all the factors except fi). MULTTHRU does not expand 
exponentiated sums. This function is the fastest way to distribute products 
(commutative or noncommutative) over sums. Since quotients are 
represented as products (see 3.3) MULTTHRU can be used to divide sums by 
products as well. 



MULTTHRUfexpi, exp2) multiplies each term in exp2 (which should be a sum or 
an equation) by expl. If expl is not itself a sum then this form is equivalent 
to MULTTHRLKexp/*exp3. 

(CI) X/(X-Y)**2-1/(X-Y)-F(X)/(X-Y)**3; 

IX F(X) 

(01) ♦ ,— 

X - Y 2 3 

(X - Y) (X - Y) 

. (C2) MULTTHRU((X-Y)**3,%); 

2 

(02) - (X - Y) ♦ X (X - Y) - F(X) 

(C3) RATEXPAND(02); 

2 

(03) - Y ♦ X Y - F(X) 

(C4) ((A+B)**10*S**2+2*A«B*S*(A*B)*«2)/(A*B*S««2); 
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(D4) 



10 2 2 2 

(B + A ) S ♦ 2 A B S ♦ A B 



2 
A B S 



(C5) MULTTHRU(X); 



10 
2 A B (B ♦ A) 

(05) - ♦ — + 

S 2 A B 

S 

(notice that (B+A)**10 is not expanded) 

(C6) MULTTHRU(A.(B+C.(D+E)+F)); 

(06) A . F ♦ A . (C . (E ♦ 0)) ♦ A . B 
(compare with similar example under EXPAND) 



XTHRU(exp) combines all terms of exp (which should be a sum) over a common 
denominator without expanding products and exponentiated sums as RATSIMP 
does. XTHRU cancels common factors in the numerator and denominator of 
rational expressions but only if the factors are explicit Sometimes it is 
better to use XTHRU before RATSIMPing an expression in order to cause 
explicit factors of the gcd of the numerator and denominator to be canceled 
thus simplifying the expression to be RATSIMPed. 

(Cl) ((X+2)**20-2*Y)/(X+Y)»«20+(X+Y)*«-19-X/(X+Y)«*20; 

20 
1 X (X + 2) v. 2 Y 
(Dl) -.-- - + 

19 20 20 

(Y + X) (Y + X) (Y ♦ X) 

(C2) XTHRU(X); 
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20 
(X ♦ 2) - Y 
(02) 

cv 
(Y ♦ X) 



PARTFRACfexp, var) expands the expression exp in partial fractions with respect 
to the main variable, var. Each power of a different denominator will be 
represented by only a single term (i.e. the decomposition is not "complete"). 
The algorithm employed is based on the fact that the denominators of the 
partial fraction expansion (the factors of the original denominator) are 
relatively prime. The numerators can be written as linear combinations of 
denominators, and the expansion falls out 

(Cl) 2/(X+2)-l/(X+l)-X/(X+l)**2i 

(C2) RATSINP(X); 

(02) 



X 



a 2 

X MX ♦ 5 X ♦ 2 

(C3) PARTFRAC(X.X); 

- 2 X - 1 2 

(03) ♦ 

2 X ♦ 2 

(X ♦ 11 



FACTORfexp) factors the expression exp, containing any number of variables or 
functions, into factors irreducible over the integers. 



FACTORfexp, p) factors exp over the field of integers with an element adjoined 
whose minimum polynomial is p. 

FACTORFLAG[FALSE] if FALSE suppresses the factoring of integer 
factors of rational expressions. 
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DONTFACTOR may be set to a list of variables with respect to which 
factoring is not to occur. (It is initially empty). Factoring also will not take 
place with respect to any variables which are less important (using the 
variable ordering assumed for CRE form) than those on the DONTFACTOR list, 
(see 6.5) 

SAVEFACTORS[FALSE] if TRUE causes the factors of an expression 
which is a product of factors to be saved by certain functions in order to 
speed up later factorizations of expressions containing some of the same 
factors. 

BERLEFACT[TRUE] if FALSE then the Kronecker factoring algorithm will 
be used otherwise the Berlekamp algorithm, which is the default, will be used 
(see [Bel, Wa4]) 

INTFACLIM[1000] is the largest divisor which will be tried when 
factoring a bignum integer. If set to FALSE (this is the case when the user 
calls FACTOR explicitly), or if the integer is a fixnum (i.e. fits in one machine 
word), complete factorization of the integer will be attempted. The user's 
setting of INTFACLIM is used for internal calls to FACTOR. Thus, INTFACLIM 
may be reset to prevent MACSYMA from taking an inordinately long time 
factoring large integers. 



GCFACTORW factors the gaussian integer n over the gaussians, i.e. numbers of 
the form a + b i where a and b are rational integers. Factors are normalized 
by making a and b non-negative. 

(Cl) FACTOR* 2**63-l); 

2 

(Dl) 73 127 337 92737 649657 7 

(C2) FACTOR(Z**2*(X+2*Y)-4*X-8*Y); 

(02) (2 Y ♦ X) (Z - 2) (Z ♦ 2) 
( C3 ) X**2*Y**2+2*X*Y**2*Y**2-X**2-2*X- 1 ; 

2 2 2 2 2 

(03) XY+2XY+Y-X-2X-1 

(C4) D0NTFACT0R:[X]t 
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(C5) FACTOR(D3/36/(Y**2*2*Y+l)); 

2 
(X ♦ 2 X ♦ 1) (Y - 1) 
(05) 

36 (Y ♦ 1) 

(C6) FACTOR(XE**(3*X)+l); 

X 2 X X 

(D6) (XE ♦ 1) (XE - XE ♦ 1) 

(C7) FACTOR(X**4+l,A**2-2); 

2 2 

(07) (X ♦ A X ♦ 1) (X - A X ♦ 1) 



When FACTOR is applied to integers, note that the value returned by 
FACTOR when used in other computations may not lead to a simplified result. 
Using Dl above, the user can check that 01 + 1; will not return 2*>3. 



FACTORSUMfexpJ tries to group terms in factors of exp which are sums into 
groups of terms such that their sum is factorable. It can recover the result of 
EXPAND((X+Y) 2 +<Z+W) 2 ) but it can't recover EXPANLK(X+1) 2 +(X+Y) 2 ) 
because the terms have variables in common. 



(CI) (X+l)*((U+Vr2+A*(V+Zr2), EXPAND; 

2 2 2 2 

(Dl)AXZ ♦ A Z +2AWXZ + 2AWZ + AV X ♦ V X 

2 2 2 2 

+ 2UVX + U X ♦ A V ♦ V +2UV + U 

(C2) FACTORSUM(X); 

2 2 

(D2) (X + 1) (A (Z ♦ W) ♦ (V ♦ U) ) 
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FACTOROUTfexp, varl,var2,...) rearranges the sum exp into a sum of terms of the 
form f(varl,var2,...)*g where g is a product of expressions not containing the 
vari's and f is factored. 

Another technique of factoring complex expressions uses the function 
SCANMAP (see Chapter 8). 



SQFR(exp) is similar to FACTOR except that the polynomial factors are "square- 
free." That is, they have factors only of degree one. This algorithm, which is 
also used by the first stage of FACTOR, utilizes the fact that a polynomial has 
in common with its nth derivative all its factors of degree > n. Thus by taking 
gcds with the polynomial of the derivatives with respect to each variable in 
the polynomial, all factors of degree > 1 can be found. 

( C 1 ) SQFR ( 4*X**4+4*X**3-3*X**2-4*X- 1 ) ; 

2 2 

(01) (X - 1) (2 X + 1) 



GFACTORfexp; factors the polynomial exp over the Gaussian integers (i. e. with 
SQRT(-l) - %l adjoined). This is like FACTOR* exp,A** 2+1) where A is V.l 

(Cl) GFACT0R(X**4-1); 

(01) (X - 1) (X ♦ 1) (X + XI) (X - XI) 



GFACTORSUMfexp; is similar to FACTORSUM but applies GFACTOR instead of 
FACTOR. 



IRREDUCIBLEfexp; returns exp flagged as being irreducible, i.e. it doesn't factor. 
Exp must be a sum. If FACTOR is ever called on an expression marked as 
irreducible it returns immediately. For example, if the value of H is a large 
expression which the user knows to be irreducible and the expression G*H is 
to be factored (where the value of G is arbitrary) then 
FACTOR(G*IRREDUCIBLE(H)) is faster than FACT0R(G*H). 
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PARTITIONfexp, var) returns a list of two expressions. They are (1) the factors 
of exp (if it is a product) or the terms of exp (if it is a sum) which don't 
contain var and, (2) the factors or terms which do. 

(Cl) PARTITI0N(2*A*X*F(X),X); 

(Dl) [ 2 A . X F(X) ] 

(C2) PARTITION(A+B,X); 

(02) [A+B.O] 



LOGCONTRACTfexp) recursively scans an exp, transforming subexpressions of the 
form al*L0G<bl) + a2*LOG(b2) + c into LOG(RATSIMP(bl^al * b2^a2)) + c 



(Cl) 2*(A*L0G(X) + 2*A*L0G(Y))t 

(C2) LOGCONTRACT(X); 

2 4 
(03) A L06(X Y ) 



ROOTSCONTRACTfexp) converts products of roots into roots of products. For 
example, ROOTSCONTRACT(SQRT(X)*Y"(3/2)); gives SQRT(X*Y~3). Currently 
it only knows about rational number exponents whose denominators are 2, 
but extension to other roots will follow. 



6.1.2 Sums and Products 



SUMfexp, ind, fo, hi) performs a summation of the values of exp as the index ind 
varies from lo to hi. If the upper and lower limits differ by an integer then 
each term in the sum is evaluated and added together. Otherwise the 
summand is evaluated with the index of summation unbound and (if SIMPSUM 
[FALSE] is TRUE) the result is simplified. This simplification may sometimes 
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be able to produce a closed form. If SIMPSUM is FALSE or if 'SUM is used, 
the value is a sum noun form which is a representation of the sigma notation 
used in mathematics. 

Sums may be differentiated, added, subtracted, or multiplied with some 
automatic simplification being performed. 

CAUCHYSUMfFALSE] when TRUE causes the Cauchy product to be used 
when multiplying sums together rather than the usual product. In the Cauchy 
product the index of the inner summation is a function of the index of the 
outer one rather than varying independently. 

GEMNDEX[I] is the alphabetic prefix used to generate the next variable 
of summation when necessary. 

GENSUMNUM[0] is the numeric suffix used to generate the next variable 
of summation. If it is set to FALSE then the index will consist only of 
GENINDEX with no numeric suffix. 

( C l ) SIMPSUM : TRUE! 

(C2) SUM(I**2+2**I,I,0,N); 

3 2 
N+12N+3N+N 
(D2) 2 ♦ 1 

6 

(C3) SUM(3**(-I),I,1,INF); 

1 
(D3) 

2 

(C4) SUM(I A 2.I,l,4)«SUH(l/I A 2 f I t l,INF); 

2 

(D5) 5 %PI 
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msUU(exp f var,low,high) performs indefinitesummation of exp with respect to 
var using a decision procedure due io R.W. Gosper, exp and the potential 
answer must be expressible as products of n* n powers, factorials, binomials 
and rational functions. ' 

UNSUM( fun,n) is the first backward difference fun(n) - fun(n-l). 

(Cl) G(P): = P*4 A N/BIN0HIAL(2*N,N); 

N 
P 4 
Ol) 6(P) :* 

BINOMIAL (2 |) ( N) 

(C2) G(IT4); 

4 N 

N 4 
(D2) 

BIN0HIALC2 N, N) 
(C3) NUSUM(D2,N,0,N); 

4 3 2 N 
2 (N ♦ 1) (63 N ♦ 112 N ♦ 18 N - 22 N ♦ 3) 4 2 
(D3) - - _ 

693 BIN0HIAL(2 N, N) 3 11 7 

(C4) UNSUH(X.-N); 

4 N 

N 4 
(04) 

BIN0HIAL(2 N, N) 



PRODUCTfexp, md, io, hi) gives the product of the values of exp as the index ind 
varies from io to hi. The evaluation is similar to that of SUM. No 
simplification of products is available at this time. 

(Cl) PRODUCT(X+I*(I+l)/2,I,l,4); 

< D1 > (X + 1) (X ♦ 3) (X ♦ 6) (X ♦ 10) 
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6.1.3 Differentiation and Integration Functions 



D\FF(exp, vl, nl, v2, n2, ...) differentiates exp with respect to each W, ni times. 
If just the first derivative with respect to one variable is desired then the 
form DIFF(exp,v) may be used If the noun form of the function is required 
(as, for example, when writing a differential equation), 'DIFF should be used 
and this will display in a two dimensional format. 

DERIVABBREV[FALSE] if TRUE will cause derivatives to display as 
subscripts. 

DIFF(exp) gives the "total differential*, that is, the sum of the derivatives 
of exp with respect to each of its variables times the function DEL of the 
variable. No further simplification of DEL is offered. 



(Cl) DIFF(EXP(F(X)),X,2); 

2 

F(X) d F(X) d 2 

(Dl) XE (--- F(X)) ♦ XE (— F(X)) 

2 dX 

dX 



(C2) DERIVABBREV: TRUES 



(C3) 'INTEGRATE(F(X,Y).Y,G(X),H(X)); 

H(X) 



(03) I F(X, Y) dY 

G(X) 
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ICA\ meat v\ . 

H(X) 

/ 
c 

< 04 > I F<X, Y) dY ♦ F(X. H(X)) H(X) - F(X. G(X)) G(X) 

3 X X X 

/ 
6(X) 



DEPENDS^ funlist l,varlistl,funlist2,varUst2,...) declares functional dependencies for 
variables to be used by DIFF. DEPENDS([F,G],[X,Yl[R,Sl[U,V f W],U,T) informs 
DIFF that F and G depend on X and Y, that R and S depend on U,V, and W, and 
that U depends on T. The arguments to DEPENDS are evaluated. The 
variables in each funlist are declared to depend on all the variables in the 
next varlist 1 A funlist can contain the name of an atomic variable or array. In 
the latter case, it is assumed that all the elements of the array depend on all 
the variables in the succeeding varlist Initially, DIFF(F,X) is 0; executing 
DEPENDS(F,X) causes future differentiations of F with respect to X to give 
DF/DX or Y x (if DERIVABBREV:TRUE). 



(CI) DEPENDS([F,G3.[X,Y],[R,S].[U,V,V],U,T); 

< D1 > CHX, Y), G(X, Y), R(U. V, V), S(U. V. W), U(T)] 

(C2) DEPENDENCIES; 

(D2 > CF(X. Y), G(X. Y), R(U, V. V), S(U. V, V), U(T)] 

(C3) DIFF(R.S,U); 

tfR dS 

dU dU 

Since MACSYMA knows the chain rule for symbolic derivatives, it takes 
advantage of the given dependencies as follows: 

<C4) DIFF(R.S,T); 

dR dU dS dU 
(M) (-- --) . S ♦ R . ( ) 

dU dT dU dT 

If we set 



1. In this command, lists of length one can be typed in directly as atoms. 
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(C5) DERIVABBREV:TRUE; 

(05) TRUE 



then re-executing the command C4, we obtain 



(C6) "C4; 

(06) (R U ) . S ♦ R . (S U ) 

U T U T 

To eliminate a previously declared dependency, the REMOVE command 
can be used. For example, to say that R no longer depends on U as declared 
in CI, the user can type REMOVE(R,DEPENDENCY). This will eliminate all 
dependencies that may have been declared for R. 



(C7) REH0VE(R, DEPENDENCY); 

(07) DONE 

(C8) "C4; 

(08) R . (S U ) 

U T 



CAVEAT: DIFF is the only MACSYMA command which uses DEPENDENCIES 
information. The arguments to INTEGRATE,LAPLACE,efc. must be given their 
dependencies explicitly in the command, e.g, INTEGRATE(F(X),X). 



GRADEF (f(xl, ..., xn), gl, ..., gn) defines the derivatives of the function f with 
respect to its n arguments. That is, df/dxi = gi, etc. If fewer than n 
gradients, say i, are given, then they refer to the first i arguments of f. The 
xi are merely dummy variables as in function definition headers and are used 
to indicate the \th argument of f. All arguments to GRADEF except the first 
are evaluated so that if g is a defined function then it is invoked and the 
result is used. 

Gradients are needed when, for example, a function is not known explicitly 
but its first derivatives are and it is desired to obtain higher order 
derivatives. GRADEF may also be used to redefine the derivatives of 
MACSYMA's predefined functions (e.g. GRADEF(SIN(X),SQRT(1-SIN(X)**2)) ). It 
is not permissible to use GRADEF on subscripted functions. 
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GRADEFS is a list of the functions which have been given gradients by 
use of the GRADEF command. 

PRINTPROPS<[a«...lGRADEF) (see 8.1.1) may be used to display 
the gradefs of the functions fl,f2,.. 

REM0VE((7V2,...] I GRADEF) may be used to eliminate the GRADEF 
property from the functions fl,f2,.... 

(Cl) DEPENDS(Y,X)t 

<C2) GRADEF(F(X.Y).X**2,G(X,Y))i 

(C3) DIFF(F(X,Y),X); 

dY 2 
(03) G(X, Y) -- ♦ X 

dX 

(C4) GRADEF(J(N,Z), 'DIFF( J(N.Z).N), 
RATSIMP(0(N-l,Z)-N/Z*J(N,Z)))t 

(C5) DIFF(J(2,X),X.2); 

2 

J(0, X) X - 3 J(l 9 X) X ♦ 6 J(2, X) 
(05) 

2 

X 



(The example above computes the second derivative of a Bessel function 
of order two. A subscripted function e.g. J[N], could not have been used 
because a gradient for it cannot be defined using GRADEF.) 



GRADEFfc, v,exp) may be used to state that the derivative of the atomic variable 
a with respect to v is exp. This automatically does a DEPENDS(a\v). For 
examples, see example 2 of Appendix III. 

PR!NTPR0PS([a/,a2,...],AT0MGRAD) (see 8.1.1) may be used to 
display the atomic gradient properties of al t a2^.. 
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REMOVE<[a7,a2...],ATOMGRAD) may be used to eliminate the ATOMGRAD 
property from al,a2, 



INTEGRATEfexp, var) integrates exp with respect to var or returns an integral 
expression (the noun form) if it cannot perform the integration. Roughly 
speaking three stages are used: 

(1) INTEGRATE sees if the integrand is of the form F(G(X))*DIFF(G(X),X) 
by testing whether the derivative of some subexpression (i.e. G(X) in the 
above case) divides the integrand. If so it looks up F in a table of integrals 
and substitutes G(X) for X in the integral of F. This may make use of 
gradients in taking the derivative. (If an unknown function appears in the 
integrand it must be eliminated in this stage or else INTEGRATE will return 
the noun form' of the integrand.) 

(2) INTEGRATE tries to match the integrand to a form for which a specific 
method can be used, e.g. trigonometric substitutions. 

(3) If the first two stages fail it uses the Risen algorithm, (see [Mo2, 
Mo4]) 

CA VEA T: INTEGRATE knows only about explicit dependencies. 



INTEGRATEfexp, var, low, high) finds the definite integral of exp with respect to 
var from low to high. Several methods are used,including direct substitution 
in the indefinite integral and contour integration (see [Wa3]). Improper 
integrals may use the names INF for positive infinity and MINF for negative 
infinity. If an integral "form" is desired for manipulation (for example, an 
integral which cannot be computed until some numbers are substituted for 
some parameters), the noun form 'INTEGRATE may be used and this will 
display with an integral sign. 

ABCONVTEST[FALSE] when TRUE causes INTEGRATE to test for absolute 
convergence. 

The function LDEFINT uses LIMIT (see 6.1.3) to evaluate the indefinite 
integral at the lower and upper limits. 

Sometimes during integration the user may be asked what the sign of an 
expression is. Suitable responses are POS; , ZERO; , or NEG; . (see 
7.1) 
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(Cl) INTEGRATE(SIN(X)**3,X); 

3 
COS (X) 

(Dl) COS<X) 

3 

<C2) INTEGRATE(X**A/(X+1)**(5/2),X,0,INF); 
IS A ♦ 1 POSITIVE, NEGATIVE, OR ZERO? 

POS; 

IS 2 A - 3 POSITIVE. NEGATIVE, OR ZERO? 

NEG; 

3 
(02) BETA(A ♦ 1, - - A) 

2 

(C3) GRA0EF(Q(X),SIN(X*»2)); 

(D3) Q(X) 

(C4) DIFF(LOG(Q(R(X))).X); 

d 2 

(-- R(X)) SIN(R (X)) 
dX 

(04) 

0(R(X)) 

(C5) INTEGRATE(X,X); 

(05) LOG(Q(R(X))) 



RISCH^exp, var) integrates exp with respect to var using the Risen algorithm. 
This currently handles the cases of nested exponentials and logarithms which 
the main part of INTEGRATE can't do. INTEGRATE will automatically apply 
R1SCH if given these cases. 

ERFFLAG[TRUE] - if FALSE prevents RISCH from introducing the ERF 
function in the answer if there were none in the integrand to begin with. 
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(Cl) RISCH(X*2*ERF(X),X); 

2 2 
- X X 3 2 
XE (XE SQRT(XPI) X ERF(X) ♦ X + 1) 
(Dl) - 

3 SQRT(XPI) 

(C2) DIFF(X,X),RATSIMP; 

2 
(D2) X ERF(X) 



CHANGEVARfexp/tey>,y,x; makes the change of variable given by f(x,y) = in all 
integrals occurring in exp with integration with respect to x; y is the new 
variable. 

(Cl) 'INTEGRATE(XE**SQRT(A*Y),Y,0,4); 

4 
/ 

[ SQRT(A) SQRT(Y) 
(Dl) I (XE ) DY 

3 
/ 


(C2) CHANGEVAR(D1,Y-Z A 2/A,Z,Y); 

2 SQRT(A) 

Z 
Z XE dZ 




(D4) 



A 
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- »—/-» «»i '«", w»/ fuiw^ me imiii vi wpas me reai vanaDie var approaches 

the value va/ from the direction dir. Dir may have the value PLUS for a limit 
from above, MINUS for a limit from below, or may be omitted (implying a two- 
sided limit is to be computed). For the method see [Wa3]. LIMIT uses the 
following special symbols: INF (positive infinity) and MINF (negative infinity). 
On output it may also use UND (undefined), IND (indefinite but bounded) and 
INFINITY (complex infinity). 

LH0SPITALLIM[4] is the maximum number of times L'Hospital's rule is 
used in LIMIT. This prevents infinite looping in cases like 
LIMIT(COT(X)/CSC(X>,X,0). 

TLIMSWITCH[FALSE] when true will cause the limit package to use 
Taylor series when possible. 

(Cl) LIMIT(X*LO6(X),X,0,PLUS); 
(01) 

(C2) LIHIT(<l*X)**(l/X) t X.*); 

(C3) LIMIT(XE**X/X r X,IIIF); 
(03> INF 

<C4) LIMIT(SIN(1/X),X,0); 
(D4) IND 



TLIMITCexp, var, val,dir) is just the function LIMIT with TLIMSWITCH set to TRUE. 

LDEFINTfexp,var,/oiv,^/); yields the definite integral of exp by using LIMIT to 
evaluate the indefinite integral of exp with respect to var at the upper limit 
high and at the lower limit low. 
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TLUEF\NT(exp,var,low,high) is just LDEFINT with TLIMSWITCH set to TRUE. 

RESIDUEfexp, var, val) computes the residue in the complex plane of the 
expression exp when the variable var assumes the value val. The residue is 
the coefficient of <var-va/)**(-l) in the Laurent series for exp. 

(CI) RESIDUE(S/(S**2+A**2).S,A*%I); 

1 
(01) 

2 

(C2) RESIDUE(SIN(A*X)/X**4,X,0); 

3 
A 
(D2) 

6 



OQE2(cfiffeq,depvar,indvar) solves ordinary differential equations,oWe<7, of first or 
second order. The dependent and independent variables are specified as the 
second and third arguments. When successful 0DE2 returns either an explicit 
or implicit solution for the dependent variable. The symbol ZC is used to 
represent the constant in the case of first order equations and %K1,7.K2 
represent the constants for second order equations. If for some reason 0DE2 
cannot obtain a solution, it returns FALSE, sometimes printing an error 
message to the user. 

(Cl) X*2*'DIFF(Y,X) ♦ 3*X*Y ' SIN(X)/X; 

2 dY • SIM(X) 

(01) x — ♦ 3 X Y • ---,-- 

dX X 

(C2) ODE2(%,Y,X); 



XC - COS(X) 
(02) Y « 

3 
X 
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6.2 Part Selection and Substitution 



Tha t..~.~ll~~~ :- »u:. «*!_, 



s functions in this section are used to extract or repiace parts of 
expressions. 



6.2.1 The Part Functions 



The Part functions make it possible to reference or replace any part of any 
MACSYMA expression. A part of a displayed expression is referred to by a set 
of indices which are non-negative integers. For example, in exponentiation the 
base is considered part 1 and the exponent part 2. In a quotient the numerator is 
part 1 and the denominator part 2. In a sum or product the \th term or factor is 
part i. In any expression the main operator is part 0. For -X the 0th part is -, for 
A~B it is -\ for DIFF(F(X),X) it is DIFF, etc. Note that unary minus is considered an 
operator. 

In MACSYMA the user has some control of the way in which expressions are 
displayed. The ordering of factors in a product or terms in a sum may be changed 
by the user (see 10.5, 6.5). The ordering of parts in the displayed 
form of an expression may differ from the ordering in the internal representation 
of the expression. 

PARTfexp, nl, ..., nk) deals with the displayed form of exp. It obtains the part of 
exp as specified by the indices nl r .. t nk. First part nl of exp is obtained, then 
part n2 of that, etc. The result is part nk of ... part n2 of part nl of exp 
Thus PART<Z+2*Y,2,1) yields 2. PART can be used to obtain an element of a 
list, a row of a matrix, etc. 

(Cl) X+Y/Z**2; 

Y 

(01) - + X 

2 
Z 
<C2) PARTCD1, 1,2,2); 

(02) 2 
(C3) 'INTEGRATE(F(X),X,A,B)*X; 
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/ 

[ 
(D3) I F(X)dX ♦ X 

] 
/ 
A 



(C4) PART(%,1,1); 

(04) F(X) 



\t4P ART (exp,nl,...,nk) is similar to PART but works on the internal representation 
of the expression (see 3.3) rather than the displayed form and thus may be 
faster since no formatting is done. Care should be taken with respect to the 
order of subexpressions in sums and products (since the order of variables in 
the internal form is often different from that in the displayed form) and in 
dealing with unary minus, subtraction, and division (since these operators are 
removed from the expression). PART(X+Y,0) or INPART(X+Y,0) yield +, though 
in order to refer to the operator it must be enclosed in V For example ...IF 
INPART(D9,0)=V THEN ... 

(CI) X+Y+W*Z; 

(01) W Z ♦ Y ♦ X 
(C2) INPART(D1,3,2); 

(02) Z 
(C3) PART(D1,1,2); 

(03) Z 

(C4) 'LIMIT(F(X)**G(X+1),X,0, MINUS); 

G(X ♦ 1) 
(D4) LIMIT F(X) 

X ->0- 

(C5) INPART(X,1,2); 

(D5) 6(X + 1) 
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r-\tr+r-%r~r\rsi i / 



uizirrut\M{exp/ reiurns me exiernai representation or exp iwrt its main 
operator). This should be useful in conjunction with PART which also deals 
with the external representation. Suppose EXP is -A . Then the internal 
representation of EXP is M * W (-1,A), while the external representation is M -"(A). 
LENGTH(EXP) gives 2, while LENGTH(DISPFORM(EXP)) gives 1. MAP(F,EXP) 
gives F(-1)*F(A), while MAP(F,DISPFORM(EXP» gives -F(A). 
DISPFORM(exp,ALL) converts the entire expression (not just the top-level) to 
external format. For example, if EXP:SIN(SQRT(X)), then FREEOF(SQRT,EXP) 
and FREEOF(SQRT,DISPFORM(EXP)) give TRUE, while 

FREEOF(SQRT,DISPFORM(EXP,ALL)) gives FALSE. 



NOUNIF Y(f) returns the noun form of the function name f. This is needed if one 
wishes to refer to the name of a verb function as if it were a noun. Note 
that some verb functions will return their noun forms if they can't be 
evaluated for certain arguments. This is also the form returned if a function 
call is preceded by a quota 

(C6) IS(INPART(D4,0)=NOUNIFY( LIMIT)); 

(D6) TRUE 



VERBIFYf # returns the function name f in its verb form. 



BOX(exp) returns exp enclosed in a box. The box is actually part of the 
expression. BOX(exp,label) encloses exp in a labeled box. label is a name 
which will be truncated in display if it is too long. Simplification will occur 
within and outside of a BOXed expression but simplifications which require 
interactions across the box boundary will not take place. 

BOXCHAR['*] - is the character used to draw the box in this and in the 
DPART and LPART functions. 



DPARTfexp, nl, ..., nk) selects the same subexpression as PART, but instead of 
just returning that subexpression as its value, it returns the whole 
expression with the selected subexpression displayed inside a box. The box 
is actually part of the expression. 
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(CI) DPART(X+Y/Z**2, 1,2,1); 

Y 
(Dl) -— ♦ X 

2 



LPARTOabel, exp, nl, ..., nk) is similar to DPART but uses a labeled box. A labeled 
box is similar to the one produced by DPART but it has a name in the top 
line. 



REMBOXfexp, arg) removes boxes from exp according to arg. If arg is 
UNLABELED then all unlabeled boxes are removed. !f arg is the name of 
some label then only boxes with that label are removed. If arg is omitted 
then all boxes labeled and unlabeled are removed. 



6.2.2 The Substitution Functions 



SUBSTfe, b, c) substitutes a for b in c. b must be an atom or a complete 
subexpression of c. For example, X+Y+Z is a complete subexpression of 
2*(X+Y+Z)/W while X+Y is not. When b does not have these characteristics, 
one may sometimes use SUBSTPART or RATSUBST (see below). 
Alternatively, if b is of the form e/f then one could use SUBST(a*f,e,c) while 
if b is of the form e**U/f) then one could use SUBST(a**f,e,c). The SUBST 
command also discerns the X Y in X^(-Y) so that SUBST(A,SQRT(X),1/SQRT(X)) 
yields 1/A. 

a and b may also be operators of an expression (enclosed in "s) or they may 
be function names. If one wishes to substitute for the independent variable 
in derivative forms then the AT function (see below) should be used. 

SUBST(eql,exp) or SUBST([eql,...,eqklexp) are other permissible forms. 
The eqi are equations indicating substitutions to be made. For each equation, 
the right side will be substituted for the left in the expression exp. 
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For expressions in CRE representation (see 3.1), SUBST, like many of 
MACSYMA's general simplification commands, works on the RATDISREPed form 
of the expressioa 

EXPTSUBST[FALSE] if TRUE permits substitutions such as Y for %E**X in 
%E**(A*X) to take place. 

(CI) SUBST(A.X*Y,X*(X+Y)**2*Y); 

2 
(Dl) Y ♦ X ♦ A 

(C2) SUBST(-%I,XI,A+B*XI); 

(02) A - XI B 



(Note that C2 is one way of obtaining the complex conjugate of an 
expression.) The following examples illustrate the difference between 
substitution (as performed by SUBST) and binding (as performed by EV). 

(C3) %PI*R.XPI:-XI; 

XPI Improper value assignment 

(C4) SUBST(X=0,OIFF(SIN(X),X)); 

(04) 1 



(C5) DIFF<SIN(X),X),X=0; 
n 






V 

attempt to differentiate wrt a 


nuaber 


(C6) MATRIX([A,B],[C,D]); 




CAB] 


(06) 




[ ] 
[CD] 


(C8) SUBST("[\HATRIX f X); 






(D8) 


EC* 


>. B], [C, D]] 
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RATSUBSTYa, b, c) substitutes a for b in c. b may be a sum, product, power, etc. 
RATSUBST knows something of the meaning of expressions whereas SUBST 
does a purely syntactic substitution. Thus SUBST(A,X+Y,X+Y+Z) returns 
X+Y+Z whereas RATSUBST would return Z+A. 

RADSUBSTFLAG[FALSE] if TRUE permits substitutions such as U for 
SQRT(X) in X. 

(CI) RATSUBST( A , X*Y*2 , X A 4*Y A 8+X A 4*Y A 3 ) ; 

3 4 

(01) A X Y + A 

(C2) 1 ♦ COS(X) ♦ C0S(X) A 2 ♦ C0S(X) A 3 ♦ C0S(X) A 4; 

4 3 2 

(D2) COS (X) ♦ COS (X) ♦ COS (X) ♦ COS(X) ♦ 1 

(C3) RATSUBST(1-SIN(X) A 2,C0S(X) A 2,%); 

4 I Z 

(03) SIN (X) ♦ COS(X) (2 - SIN (X)) - 3 SIN (X) ♦ 3 



SUBSTPARTfx, exp, nl, ..., nk) substitutes x for the subexpression picked out by 
the rest of the arguments as in PART. It returns the new value of exp. 
x may be some operator to be substituted for an operator of exp. In this 
case it is enclosed in "s. 



(CI) l/(X A 2+2); 
(01) 

(C2) SUBSTPART(3/2,%,2,1,2); 



1 



2 
X ♦ 2 



\VC) 


3/2 




X +2 


(C3) A*X+F(B,Y); 




(D3) 


A X + F(B, Y) 
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KCA) 5UB5TPARTi Si "i' a ,X,i t 0); 

(04) X ♦ F(B, Y) ♦ A 

(C5) X A 2 + X ♦ It 



<C6) SUBSTPART( "[■,%, 0); 


2 
[X . X. 1] 


(06) 



SUBSTINPARTfx, exp, nl t ...) is like SUBSTPART but works on the internal 
representation of exp. 

(CI) X.'DIFF(F(X),X.2); 

2 
d 

(01) X . ( — F(X)) 

2 
dX 

(C2) SUBSTINPART(IT2,%.2); 

2 

(02) X . 

(C3) SUBSTINPART(F1,F[1](X+1),0); 

(03) F1(X ♦ 1) 
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Additional Information 

If the last argument to a Part function is a list of indices then several 
subexpressions are picked out, each one corresponding to an index of the list. 
Thus PART(X+Y+Z,[1,3]) is Z+X, 

PIECE holds the last expression selected when using the Part functions. 
It is set during the execution of the function and thus may be referred to in 
the function itself as shown below. 

If PARTSWITCH[FALSE] is set to TRUE then END is returned when a 
selected part of an expression doesn't exist, otherwise an error message is 
given. 

(CI) 27*Y**34.54*X»Y««2+36*X««2*Y+Y+8*X«*3+X+1; 

3 2 2 3 

(01) 27 Y ♦ 54 X Y ♦ 36 X Y ♦ Y ♦ 8 X ♦ X ♦ 1 

\c2; FnRi\VL,c,n,jji; 

2 

(02) 54 Y 

(C3) SQRT( PIECE/54); 

(03) Y 

(C4) SUBSTPART(FACT0R(PIECE),D1,[1,2,3,5]); 

3 

(04) (3 Y ♦ 2 X) ♦ Y ♦ X ♦ 1 

(C5) 1/X+Y/X-l/Z; 

1 Y 1 
(D5) --♦- + - 

Z X X 

(C6) SUBSTPART(XTHRU(PIECE).X,[2,3]); 
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Y ♦ 1 1 
(06) 

X 2 



ATVALUEfYorm, list, value) enables the user to assign the boundary value value to 
form at the points specified by list 

(Cl) ATVALUE(F(X,Y).[X=0,Y=l],A**2)t 

The form must be a function, f(vl,v2 r ..) , or a derivative, 
DIFF(f(vl,v2,...) f vi,ni,vj,nj,...) in which the functional arguments explicitly appear 
(ni is the order of differentiation with respect vi). 

The list of equations determine the "boundary" at which the value is 
given; list may be a list of equations, as above, or a single equation, vi ■ exp. 

The symbols ©1, ©2 r .. will be used to represent the functional variables 
vl,v2,... when atvalues are displayed 

PRINTPR0PS([f7, /!£..], ATVALUE) will display the atvalues of the 
functions flJ2 r .. as specified in previously given uses of the ATVALUE 
function, (see 8.1.1) If the list contains just one element then the 
element can be given without being in a list If a first argument of ALL is 
given then atvalues for all functions which have them will be displayed 

ATfexp, fist) will evaluate exp (which may be any expression) with the variables 
assuming the values as specified for them in the list of equations or the single 
equation similar to that given to the ATVALUE function. If a subexpression 
depends on any of the variables in list but it hasn't had an at value specified 
and it can't be evaluated then a noun form of the AT will be returned which 
will display in a two-dimensional form. 

(Cl) ATVALUE(F(X,Y).[X*0,Y*1],A*»2); 

2 

(Dl) A 

(C2) ATVALUE('DIFF(F(X,Y),X),XsO l Y*l); 
iOZ) §2*1 
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(C3) PRINTPROPS(ALL.ATVALUE); 

! 

D ! 

-— F(*l, §2)! 

Dei i 



« 32 ♦ 1 



= 



F(0, 1) * A 

(*>*) DONE 

(C4) DIFF(4*F(X,Y)**2-U(X,Y)**2,X); 

d d 

(04) 8 F(X, Y) (-- F(X, Yj) - 2 U(X. Y) (- U(X, Y)) 

<IX dX 



(C5) AT(X,[JC>0,Y*1]); 
(05) 



2 d 

16 A - 2 U(0, 1)C— U(X, Y) 

dX 



X = 0, Y r 1 



6.2.3 More Functions for Part Extraction 



LISTOFVARSfexp; yields a list of the variables in exp. 

LISTCONSTVARS[FALSE] if TRUE will cause LISTOFVARS to include 7.E, 
7oPI, %l, and any variables declared constant (see 8.1) in the list it 
returns if they appear in exp. The default is to omit these. 

(CI) LIST0FVARS(F(X[1]+Y)/G**(2+A)); 

< D1 > [X[1J, Y, A, G] 
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1. v may be an atom, or complete subexpression of exp e.g., X, SIN(X), 
A[l+ll X+Y, etc. (In the last case the expression (X+Y) should occur in exp). 
Sometimes it may be necessary to expand or factor exp in order to make v 11 
explicit. This is not done automatically by COEFF. 

(Cl) COEFF(2*A*TAN(X)+TAN(X)+B=5*TAN(X)+3,TAN(X)); 

(Dl) 2 A ♦ 1 = 5 

(C2) COEFF(Y+X*%E**X+1,X,0); 

(02) Y+ 1 



RATCOEFfexp, v, n) returns the coefficient, C, of the expression v**n in the 
expression exp. n may be omitted if it is 1. C will be free (except possibly 
in a non-rational sense) of the variables in v. If no coefficient of this type 
exists, zero will be returned. RATCOEF expands and rationally simplifies its 
first argument and thus it may produce answers different from those of 
COEFF which is purely syntactic. Thus RATC0EF((X+1)/Y+X,X) returns 
(Y+D/Y whereas COEFF returns 1. RATC0EF(exp,v,0) is currently the same 
as RATSUBST(0,v,exp). Therefore if v occurs to any negative powers, 
RATCOEF should not be used. Since exp is rationally simplified before it is 
examined, coefficients may not appear quite the way they were envisioned 

(Cl) S:A*X+B*X+5t 

(C2) RATCOEF(S,A+B); 

(D2) X 



BOTHCOEFfexp, var) returns a list whose first member is the coefficient of var in 
exp (as found by RATCOEF if exp is in CRE form otherwise by COEFF) and 
whose second member is the remaining part of exp. That is, [A,B] where 
exp= A* var+B. 
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(Cl) ISLINEAR(EXP,VAR):=BLOCK([C], 

C:BOTHCOEF(RAT(EXP f VAR),VAR) f 
IS(FREEOF(VAR,C) AND C[l]#0))t 



(C2) ISLINEAR((R**2-(X-R)**2)/X,X); 
(02) TRUE 



ISOLATEfexp, var) returns exp with subexpressions which are sums and which do 
not contain var replaced by intermediate expression labels (these being 
atomic symbols like El, E2, ...). This is often useful to avoid unnecessary 
expansion of subexpressions which don't contain the variable of interest. 
Since the intermediate labels are bound to the subexpressions they can all be 
substituted back by evaluating the expression in which they occur. 

EXPTISOLATE[FALSE] if TRUE will cause ISOLATE to examine exponents 
of atoms (like %E) which contain var. 

(Cl) (A+Br4*(l+X*(2*X+(C+D)*2)); 

4 2 

(01) (B ♦ A) (X (2 X ♦ (0 ♦ C) ) ♦ 1) 

(C2) IS0LATE(%,X); 

2 
<E2) (0 ♦ C) 

4 
(E3) (B ♦ A) 

(03) E3 (X (2 X ♦ E2) ♦ 1) 

(C4) RATEXPAND(D3)» 

(C5) EV(%); 

4 2 4 2 4 

(05) 2 (B ♦ A) X + (B ♦ A) (D + C) X ♦ (B ♦ A) 

(C6) (A+B)*(X+A+Br2*EXP(X A 2+A*X+B); 
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2 

2 X ♦ A X ♦ B 
(D6) <B ♦ A) (X ♦ B ♦ A) XE 

(C7) ISOLATE(X.X),EXPTISOLATE:TRUE; 

(E7) B*A 

B 

2 
2 X ♦ A X 
(08) E7 E8 (X + E7) XE 



PICKAPARTfexprCfepW will assign E labels to all subexpressions of exp down to 
the specified integer depth. TNs is useful for dealing with large expressions 
and for automatically assigning parts of an expression to a variable without 
having to use the Part functions. 

(Cl) INTEGRATE* l/(X*3*2),X)t 
(C2) PICKAPART(Dl.l); 

1/3 
L06(X ♦ 2 ) 
(E2) 

2/3 
3 2 

1/3 
2 X - 2 

ATA«( ) 

1/3 
2 SQRT(3) 
(E3) 

2/3 
2 SQRT(3) 
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2 1/3 2/3 
LOG(X -2 X ♦ 2 ) 
(E4) 

2/3 
6 2 

(04) E4 ♦ E3 ♦ E2 



REVEM(exp,depth) will display exp to the specified integer depth with the length 
of each part indicated. Sums will be displayed as SUM(n) and. products as 
PRODUCT(n) where n is the number of subparts of the sum or product. 
Exponentials will be displayed as EXPT. 



(Cl) INTEGRATE* 1/(X*3+2),X)I 

(C2) REVEAL(%,2); 

(02) PR0DUCT(3) ♦ PR00UCT(3) ♦ PRO0UCT(3) 

(C3) REVEAL(D1,3); 

EXPT LOG EXPT LOG 

(03) ♦ EXPT EXPT ATAN ♦ 

6 3 



NUMFACTORfexp; gives the numerical factor multiplying the expression exp 
which should be a single term, if the gcd of all the term coefficients in a sum 
is desired the CONTENT function (see 6.5) may be used 



(Cl) GAMMA(7/2); 




(01) 


15 SQRT(XPI) 




8 


(C2) NUMFACTOR(X) 






15 


(02) 


-- 




8 
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f Ml W ** I **r\f+f r/ £1 v w«r till? lll|IIU(ls C»f\}#IIWl» O/ApWIWIK VI 7 III W\fS. «)WHISUMW« II IIIOJ 

be necessary to expand exp since this is not done automatically by WPOW. 
Thus HIP0W(Y**3*X**2+X*Y**4»X) is Z 



LOPOWYexp, vj gives the lowest exponent of v which explicitly appears in exp. 
Thus L0P0W((X+Y)**2-KX+Y)**A,XVir) is MIN(A,2). 



DERIVDEGREEfexp, dv, /VJ finds the highest degree of the derivative of the 
dependent variable dv with respect to the independent variable iv occurring 
in exp. 

(CI) 'DIFF(Y,X,2)+'DIFF(Y,Z,3)*2+'DIFF(Y,X)*X**2t 

(C2) DERIVDEGREE(X,Y.X); 

(02) 2 



The next several functions deal with complex variables. The user should 
note the following conventions. 

1) all variables are assumed to take on real values exclusively; 

2) all functions are assumed to be real-valued; 

3) the complex argument is maintained in the half-open interval 
(-*-,*■] whenever possible; 

4) the argument of is (arbitrarily) assumed to be 0, although 
normally the user need not worry about this, since 0*XE A (XI*0) is 
simplified to 0; 

5) trigonometric functions are normally assumed to take on 
their principal values. 



REALPARTfexp) gives the real part of exp. REALPART and IMAGPART will work 
on expressions involving trigonometic and hyperbolic functions, as well as 
SQRT, LOG, and exponentiation. 
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IMAGPARTYexp; returns the imaginary part of the expression exp. 

The real or imaginary part of an expression of the form Z N , where Z is not 
purely real, will be algebraic if n <= MAXPOSEX; otherwise, for compactness,* will 
be expressed as ABS(Z)N * COS(N*ARG Z) or ABS(Z) N * SIN(N*ARG Z). 

RECTFORMCexp; returns an expression of the form A + B*7.l, where A and B are 
purely real. 

POLARFORMfexp; returns R*7.ET/.I*THETA) where R and THETA are purely real. 

CAVEAT: Simplification of algebraic and transcendental functions of a complex 
variable may give rise to apparent factors, 7.1. For example, SQRT(-C+D> may be 
transformed to 7.I*SQRT(C-D). 

CABSfexp; returns the complex absolute value (the complex modulus) of exp. 

CARGCexp; returns the argument (phase angle) of exp. Due to the conventions 
and restrictions (described above), principal value cannot be guaranteed. 

(Cl.) RECTF0RM(SIN(2*XI+X)); 

(01) C0SH(2) SIN(X) ♦ XI SINH(2) COS(X) 

(C2) POLARFORM(X); 

2 2 2 2 
(D2) SQRT(COSH (2) SIN (X) ♦ SINH (2) COS (X)) 

%I ATAN2(SINH(2) COS(X), C0SH(2) SIN(X)) 
XE 
(C3) RECTFORM(LOG(3+4*XI)); 

(D3) L0G(5) ♦ XI ATAN2(4,3) 

(C4) POLARFORH(X); 

2 2 XI ATAN2(ATAN2(4, 3), L0G(5)) 

(D4) SQRT(LOG (5) + ATAN2 (4, 3)) XE 
(C5) RECTFORM((2+3.5*XI) A .25),NUMER; 
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(D5) 0.36825881 XI ♦ 1.36826627 

(C6) POLARFORM(D5); 

0.26291253 XI 
(D6 > 1.416957 XE 



LHS W re \ UmS lhC ,eU Side of lhe equation eqrt ,f e « n ls not an e <^tion, then 
LHS(egn) = eqa 

RHS then > RHS<'eS) = e right *" " "" **"*'" "* " "" '' "* *" 6qU8ti0n ' 
NUM^exp; obtains the numerator, expl, of the rational expression exp = 

DEN expf/ei a 61 "'" 8 * he den0min8to, '• exp2 > °* the rational expression exp = 

The above two commands do not alter the internal representations of 

S eSS 'wnr«™„ ha T e the desirable ^P^y th8t '<"■ *» expressions 
NUM(exp)/DENOM(exp) is the same as exp. 

FIRSTYexp; yields the first part of exp which may result in the first element of a 

a u 6 ,.? r ° W ° f a matrix ' the first term of a sum - etc. Note that FIRST 
and the following two functions work on the form of exp which is displayed 

? ™?r u rm W Ch J S typed on inpul " the variable INFLAG[FALSE] is set 
o TRUE however, these functions will look at the internal form of exp. Note 

y > .mc, »'n P '' ™ r a -° rders expressions (see 3.3). Thus FIRST(X + Y) will be 
X ,f INFLAG is TRUE and Y if INFLAG is FALSE. <FIRST(Y+X) gives the same 



RESTYexA ^yields exp with its first n elements removed if n is positive and its 
last -n elements removed if n is negative. If n is 1 it may be omitted. Exp 
may be a list, matrix, or other expression, if INFLAG:TRUE the internal form 
of exp will be used. 
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LAST(exp) yields the last part (term, row, element, etc.) of the exp. If 
INFLAG:TRUE the internal form of exp will be used. 



DELETEfexp7, exp2) removes all occurrences of exp I from exp2. Exp I may be a 
term of exp2 (if it is a sum) or a factor of exp2 (if it is a product). 

(Cl) DELETE(SIN(X),X+SIN(X)+Y); 
(01) Y + X 



LENGTHfexpJ gives the number of parts in the internal form of exp. For lists this 
is the number of elements, for matrices it is the number of rows, and for 
sums it is the number of terms. However for products it may not always 
yield the number of factors that would be displayed because of the fact that 
-E is represented internally as -1*E and A/B is represented internally by 
A*B"(-lj. (cf. DISPFORM) 



NTERMSfexpj gives the number of terms that exp would have if it were fully 
expanded out and no cancellations or combinations of terms occurred. Note 
that expressions like SIN(E), SQRT(E), EXP(E), etc. count as just one term 
regardless of how many terms E has (if it is a sum). 
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— s - , "' l,Jf,w Wm " h " ,c rOwis ui equations or yieia information 

concerning the roots. 

NROOTS(poly, low, high) finds the number of real roots of the real univariate 
polynomial poly in the half-open interval (low,Hghl The endpoints of the 
mterval may also be MINF.INF respectively for minus infinity and plus infinity 
NROOTS(poiy> is equivalent to NROOTS(po/y,MINF,INF). The method of Sturm 
sequences is used, (see Heindel in [A1J) 

(Cl) POLYl:X**10-2*X**4+l/2t 

(C2) NRO0TS(P0LYl,-6,9.1); 

RAT REPLACEO 0.5 BY 1/2 = 0.5 

(D2) 4 



REALROOTS(po/y, bound) finds all of the real roots of the real univariate 
polynomial poly within a tolerance of bound which, if less than 1, causes all 
integral roots to be found exactly. The parameter bound may be arbitrarily 
small in order to achieve any desired accuracy. The first argument may also 
be an equation. REALR00TS(po/v) is equivalent to 

REALROOTS(po/y,ROOTSEPSILON>. R00TSEPSIL0N[1.0E-7] is a real number 
used to establish the confidence interval for the roots. 

(Cl) REALROOTS(X**5+X+l,5.0E-6); 



(El) 




395773 
X * 

524288 


(Dl) 




[El] 


(C2) El, FLOAT; 






(02) 


X 


= - 0.75487709 


(C3) PART(C1,1); 






(D3) 




5 
X ♦ X ♦ 1 
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(C4) %,D2; 

(D4) 1.50687992E-6 



ALLROOTSCpo/y; finds all the real and complex roots of the real polynomial poly 
which must be univariate and may be an equation. For complex polynomials 
an algorithm by Jenkins and Traub is used;* for real polynomials the algorithm 
used is due to Jenkins. 2 The flag POLYFACTOR[FALSE] when true causes 
ALLROOTS to factor the polynomial over the real numbers if the polynomial is 
real, or over the complex numbers, if the polynomial is complex. 

(Cl) (2*X+1)**3=13.5*(X**5+1); 

3 5 
(01) (2X4-1) = 13.5 (X + 1) 

(C2) ALLRQGTS(X); 

/ro\ w _ i «i tveec 

(E3) X = 0.829675 

(E4) X * - 0.96596254 XI - 0.40695972 

(E5) X = 0.96596254 XI - 0.40695972 

(E6) X = 1.0 

(06) [E2, E3, E4, E5, E6] 



LINSOLVEf/expi, exp2, ...], [varl, var2, ...]) solves the list of simultaneous linear 
equations for the list of variables. The expi must each be linear in the 
variables and may be equations. LINSOLVE does no error checking to assure 
linearity. 



1. Algorithm 419, Comm. ACM, vol. 15, (1972), p. 97 

2. Algorithm 493, TOMS, vol. 1, (1975), p.178. 
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If Rl HRAI Qfll Y/FTFAI CP1 U «** »« TDiir »i :-i_i„ ...u : _i_ .... 

— — — ■ — ~%»— „_ L . ..k.M^.j ,„ «v.» %w ihul %ucii vciriauies wnicn are 

SOLVEd for will be set to the solution of the set of simultaneous equations. 

BACKSUBST[TRUE] if set to FALSE will prevent back substitution after 
the equations have been triangularized. This may be necessary in very big 
problems where back substitution would cause the storage capacity to be 
exceeded. 

(Cl) X+Z=Yt 

(C2) 2*A*X-Y=2*A**2t 

<C3) Y-2*Z=21 

<C4) LINSOLVE([D1,02,D3],[X.Y,Z]),6LOBALSOLVE:TRUE; 
SOLUTION 

<E4) X : A ♦ 1 

<E5) Y:2A 

(E6) Z : A - 1 

< 06 ) [E4, E5, E6] 

ALGSYS([expl, exp2, ..J [varl, var2, ...]) solves the list of simultaneous 
polynomials or polynomial equations (which can be non-linear) for the list of 
variables. The symbols 7.R1, 7.R2, etc. will be used to represent arbitrary 
parameters when needed for the solution. In the process described below, 
ALGSYS is entered recursively if necessary. 

The method is as follows: 

(1) First the equations are FACTORed and split into subsystems. 

(2) For each subsystem $t\ an equation fand a variable var are selected 
(the var is chosen to have lowest nonzero degree). Then the resultant of E 
and Ej with respect to var is computed for each of the remaining equations Ej 
in the subsystem Si. This yields a new subsystem S'i in one fewer variables 
(var has been eliminated). The process now returns to (1). 
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(3) Eventually, a subsystem consisting of a single equation is obtained. If 
the equation is multivariate and no approximations in the form of floating 
point numbers have been introduced, then SOLVE is called to find an exact 
solution. 3 

If the equation is univariate and is either linear, quadratic, or bi- 
quadratic, then again SOLVE is called if no approximations have been 
introduced. If approximations have been introduced then if the switch 
REALROOTS[TRUE]:TRUE, the function REALROOTS is called to find the real- 
valued solutions. If REALROOTS:FALSE then ALLROOTS is called which looks 
for real and complex-valued solutions. If ALGSYS produces a solution which 
has fewer significant digits than required, the user can change the value of 
ALGEPSILON[10 8 ] to a higher value. 

(4) Finally, the solutions obtained in step (3) are re-inserted into 
previous levels and the solution process returns to (1). 

The user should be aware of several caveats. 

When ALGSYS encounters a multivariate equation which already contains 
floating point approximations, then, presently, it does not attempt to apply 
exact methods to such equations and prints the message: ALGSYS CANNOT 
SOLVE— SYSTEM TOO COMPLICATED. 

Interactions with RADCAN can produce large or complicated expressions. 
In that case, the user may use PICKAPART or REVEAL to analyze the solution. 
Occasionally, RADCAN may introduce an apparent %! into a solution which is 
actually real-valued. To prevent the omission of possible solutions, the user 
may prefer to set REA'-OftLY["~RUE]:FALSE. 

(CI) X+Z-Yi 

(C2) X+B*Y*Z -At 

(C3) X~2+C*Z -D; 

(C4) ALGSYS([D1,D2,D3],[X,Y,Z]); 

(D4) [] 



3. The user should realize that SOLVE may not be able to produce a solution 
or if it does the solution may be a very large expression. 
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(C5) X+Z-Y A 2i 



(C6) ALGSYS([01,02,D5),[X,Y,Z]); 

B - A A - 1 
(D6) [[X = , Y = 1, Z * 3. [X « A, V » 0, Z - - A]] 

B - 1 B - 1 

(C7) X+B*Y*Z*X -At 

(C8) ALGSYS([D1.D5,D7].[X,Y,Z]); 

2 
SQRT(B -4AM2B*1)*I*1 

(08) [[X = Y ■ 1, 

2 B 

2 

S0RT(B ♦ (2 - 4 A) B ♦ 1) ♦ (1 - 2 A) B ♦ 1 

Z = -1. 

2 2 

B SQRT(B ♦U-4A)I»U»I *l 

2 
- SQRT(B -4AB + 2B+D + B+1 
[X = Y ■ 1. 

2 B 

2 
SQRT(B ♦ (2 - 4 A) B ♦ 1) ♦ (2 A - 1) B - 1 

z = 3. 

2 2 

B SQRT(B ♦(2-4A)B+l)-B-B 



[X = A, Y = 0, Z = ■ A]] 



SOLVEfexp, var) solves the algebraic equation exp for the variable var and 
returns a list of solution equations in var. If exp is not an equation, it is 
assumed to be an expression to be set equal to zero. Var may be a function 
{e.g. F(X)), or other non-atomic expression except a sum or product. It may 
be omitted if exp contains only one variable. Exp may be a rational 
expression, and may contain trigonometric functions, exponentials, etc. 
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The following method is used: 

Let E be the expression and X be the variable. If E is linear in X then it 
is trivially solved for X. Otherwise if E is of the form A*X**N+B then the 
result is (-B/A)**(l/N) times the Nth roots of unity. 

If E is not linear in X then the gcd of the exponents of X in E (say N) is 
divided into the exponents and the multiplicity of the roots is multiplied by N. 
Then SOLVE is called again on the result. 

If E factors then SOLVE is called on each of the factors. Finally SOLVE 
will use the quadratic, cubic, or quartic formulas where necessary. 

In the case where E is a polynomial in some function of the variable to be 
solved for, say F(X), then it is first solved for F(X) (call the result C), then 
the equation F(X)=C can be solved for X provided the inverse of the function 
F is known. 

BREAKUP[TRUE] if FALSE will cause SOLVE to express the solutions of 
cubic or quartic equations as single expressions rather than as made up of 
several common subexpressions which is the default. 

MULTIPLICITIES[N0T7.SET7.YET] - will be set to a list of the 
multiplicities of the individual solutions returned by SOLVE, REALROOTS, or 
ALLROOTS. 

SOLVEFACTORS[TRUE] - if FALSE then SOLVE will not try to factor the 
expression. The FALSE setting may be desired in some cases where factoring 
is not necessary. 

SOLVERADCAN[FALSE] - if TRUE then SOLVE will use RADCAN which 
will make SOLVE slower but will allow certain problems containing 
exponentials and logs to be solved. 

When SOLVing polynomials with large integer coefficients, it may be 
useful to reset INTFACLIM. 



SQL\JE([eql, ..., eqn], [vl, ..., vn]) solves a system of simultaneous (linear or non- 
linear) polynomial equations by calling LINSOLVE or ALGSYS and returns a list 
of the solution lists in the variables. In the case of LINSOLVE this list would 
contain a single list of solutions. It takes two lists as arguments. The first list 
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(eg/, i = i,...,n/ represents me equations io De soivea; me secona hsi is a nsi 
of the unknowns to be determined. If the total number of variables in the 
equations is equal to the number of equations, the second argument-list may 
be omitted. For linear systems if the given equations are not compatible, the 
message INCONSISTENT will be displayed; if no unique solution exists, then 
SINGULAR will be displayed. DISPFLAGfTRUE] when set to FALSE within a 
BLOCK will inhibit the display of output generated by the Solve functions 
called from within the BLOCK. 

SOLVETRIGWARN[TRUE] if set to FALSE will inhibit printing by SOLVE of the 
warning message saying that it is using inverse trigonometric functions to 
solve the equation, and thereby losing solutions. 

SOLVEDECOMPOSES[TRUE] if TRUE, will induce SOLVE to use 
POLYDECOMP (see below) in attempting to solve polynomials. * 

PROGRAMMODEfFALSE] when TRUE will inhibit SOLVE from printing E- 
labels and will force SOLVE to return its answers explicitly as elements in a 
list 

SOLVEEXPLICIT[FALSE] if FALSE, inhibits SOLVE from returning implicit 
solutions i.e. of the form F(x)*0. 

(CI) S0LVE(ASIN(C0S(3*X))*(F(X)-1),X); 
Solution 

XPI 
<E1) X ■ — 

6 
The roots of 

(E2) F(X) « 1 

(D2) [E1.E2] 

(C3) SOLVERADCAN: TRUES 

<C4) SOLVE(5**F(X)=125,F(X)); 

(D4) F(X) * 3 

(C5) [4*X**2-Y**2=12,X*Y-X=23 



4. Under certain circumstances (e.g. if there is a variable in the exponent), 
the implicit "solution" may quite complex 
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2 2 
(D5) [4 X - Y = 12, X Y - X « 2] 

(C6) 50LVE(D5,[X,Y]); 

(06) [[Y = - 0.15356758, 

X = - 1.733752], [Y * 2.0, X = 2.0]] 

(C7) SOLVE(X*3+A*X*l,X); 

3 
SQRT(4 A ♦ 27) 
(E7) 

6 SQRT(3) 
1 1/3 

\to; jt7 - -J 

2 

Cm 1ITTOM 

XI SQRT(3) 1 

( ) A 

XI SQRT(3) 1 2 2 
(E9) X = ( ) £8 

Z Z 3 E8 

XI SQRT(3) 1 

( ) A 

XI SQRT(3) 1 2 2 
(E10) X = ( ) E8 

Z 2 3 E8 

A 

(Ell) X = E8 

3 E8 

(DID [E9, E10, Ell] 
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ruL i uLV/umrif;yj/,vflf/ reiurns a nst, ui puiynwrniais ^i i\ vari t \c\ var/,...in\ var/j sucn 

that poly = fl(f2(.;.fn(var)...)). There is no other decomposition which involves 
more polynomials excepting linear fi. 
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6.4 The Matrix Functions 



Matrix multiplication is effected by using the dot operator, V, which is also 
convenient if the user wishes to represent other non-commutative algebraic 
operations (see 6.4.1). The exponential of the . operation is W ^ M . 

Thus, for a matrix A, A. A = A*^2 and, if it exists, A~-l is the inverse of A. 

The operations +,-,*,** are all element-by-element operations; all operations 
are normally carried out in full, including the . (dot) operation. Many switches 
exist for controlling simplification rules involving dot and matrix-list operations 
(see below). 



ENTERMATRlXffy n) allows one to enter a matrix element by element with 
MACSYMA requesting values for each of the mn entries. 

(Cl) ENTERMATRIX(2,1); 
ROW 1 COLUMN 1 X+Y/2; 
ROW 2 COLUMN 1 34; 

MATRIX-ENTEREO 

C Y ] 

[ - ♦ X ] 

(01) [ 2 ] 

C 3 

C 34 ] 



MATRIXfrowi, ..., rown) defines a rectangular matrix with the indicated rows. 
Each row has the form of a list of expressions, e.g. [A, X**2, Y, 0] is a list of 
4 elements. 



GENMATRIXfarray, ,'2, j2, il, jl) generates a matrix from the array using 
array(iljl) for the first (upper-left) element and array(i2,j2) for the last 
(lower-right) element of the matrix. If j 1 =i 1 then jl may be omitted. If 
jl=il = l then il and jl may both be omitted. If a selected element of the 
array doesn't exist a symbolic one will be used. 
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(Cl) H[I 9 J]:«1/(I+J-1)S 
(C2) GENMATRIX(H,3,3); 



(02) 



r 
L 


i 


1 1 
*j 


Cl 


- 


-] 


[ 


2 


3] 


c 




3 


[1 


1 


1] 


c- 


- 


-] 


C2 


3 


4] 


[ 




3 


[1 


1 


13 


[- 


- 


-3 


[3 


4 


53 



COPYMATRIXfM creates a copy of the matrix M. This is the only way to make a 
copy aside from recreating M elementwise. Copying a matrix may be useful 
when SETELMX is used (see below). 



COPYLISTOJ creates a copy of the list L 

ADDROW<W appends the row given by the list / onto the matrix U 

\D£KT(n) produces an n by n identity matrix 



DIAGMATRIXfo x) returns a diagonal matrix of size n by n with the diagonal 
elements all x An identity matrix is created by DIAGMATRIX(n,l), or one may 
use lDENT(n). 



EMATRIXfm, n, x, i, j) will create an m by n matrix all of whose elements are zero 
except for the i,j element which is x 
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MATRIXMAP<Yn, M) will map the function fn onto each element of the matrix M. 

SETELMXfx, /; j, M) changes the ij element of M to x The altered matrix is 
returned as the value. The notation M[',f]* may also be used, altering M in a 
similar manner, but returning x as the value. 

COEFMATRIXtfeqr/, ..J, [varl, ...]) the coefficient matrix for the variables varL 
of the system of linear equations eql r .. 

AUGCOEFMATRIXtfeqi, ..J, [varl, ...]) the augmented coefficient matrix for the 
variables varl,... of the system of linear equations eql,.... This is the 
coefficient matrix with a column adjoined for the constant terms in each 
equation (i.e. those not dependent upon varl r „). 

(CI) [ 2*X= ( A- 1 )*Ys 5*B , A*X*B*Y>C=0 ]i 
(C.?\ AJicrnccMATDTv/v rv vi«. 

[2 1 - A 5 B ] 
(02) [ j 

[A B - C] 

COL(M,i) gives a matrix of the /th column of the matrix M. 
ROVvYM, i) gives a matrix of the /th row of matrix M. 



SUBMATRIXfm/, ..., M, nl, ...) creates a new matrix composed of the matrix M 
with rows mi deleted, and columns ni deleted. 



MINORA, i, j) computes the ij minor of the matrix M. That is, M wjth row / and 
column j removed. 
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i i\niwi v/ok.|frr/ pi wuu^cs mc iiaii9pu9G vi m. 



ECHELONS produces the echelon form of M. That is, M with elementary row 
operations performed on it such that the first non-zero element in each row 
in the resulting matrix is a one and the column elements under the first one in 
each row are all zero. 



(C3) ECHELON(02); 



(D3) 



(02 Is as above) 
A - 1 5 B 



2 C ♦ 5 A 1 



2 ■ + A - A 



TRIANGULARIZEM produces the upper triangular form of the matrix M which 
needn't be square. 



(C4) TRIANGUIARIZE(D2); 

1 ♦ A 



(D4) 



[2 1 ♦ A SB ] 

t 1 

i 2 ] 

[0 2 B ♦ A - A -2C-.SAI] 



HAUK(M) computes the rank of the matrix M. That is, the order of the largest 
non-singular subdeterminant of M. 



(C5) RANK(D2); 
(05) 
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DETERMINANT^ computes the determinant of M by a method similar to Gaussian 
elimination. The form of the result depends upon the setting of the switch 
RATMX (see below). There is a special routine for dealing with sparse 
determinants which can be used by setting the switches RATMX:TRUE and 
SPARSE:TRUE. 



NEWDETfM,^ also computes the determinant of M but uses the Johnson- 
Gentleman tree minor algorithm [GelJ M may be the name of a matrix or 
array. The argument n is the order; it is optional if M is a matrix. 



CHARPOLYW, var) computes the characteristic polynomial for M with respect to 
var. That is, DETERMINANT^ - DIAGMATRIX( LENGTH* M>, vat)). 



(C2) A:MATRIX([3,1],[2,4]); 






[3 1] 


(02) 


C 3 




C2 4] 



(C3) CHARP0LY( A, LAMBDA); 



(D3) 



LAMBDA - 7 LAMBDA ♦ 10 



(C4) SOLVE(X); 
SOLUTION 



(E4) 



LAMBDA = 2 



(E5) 
(D5) 



LAMBDA = 5 
[E4, E5] 



(C6) X:MATRIX([X1],[X2]); 



(06) 



[XI] 
C 3 
[X2] 



(C7) A.X-LAMBDA*X,E5; 



(D7) 



[ X2 - 2 XI ] 

[ ] 

[ - X2 + 2 XI] 
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(C6) D7[i,i]s0; 

(08) X2 - 2 XI » 

(C9) Xl**2+X2**2=l; 

2 2 

(09) X2 ♦ XI « 1 

(CIO) S0LVE([D8.D9],[X1,X2]); 

(010) CCX2 r - 0.89442714, XI = - 0.44721357], 

[X2 = 0.89442714, XI * 0.44721357]] 

Options Relating to Matrices 
Note: MX stands for Matrix and SC stands for Scalar 



By resetting the options LMXCHAR and RMXCHAR (with the defaults [ and ] 
respectively), the user can specify the delimiters used in the display of matrices. 

RATMX[FALSE] - if FALSE will cause determinant and matrix addition, 
subtraction, and multiplication to be performed in the representation of the matrix 
elements and will cause the result of matrix inverse to be left in the 
representation of the matrix elements. If it is TRUE, the 4 operations mentioned 
above will be performed in CRE form and the result of matrix inverse will be in 
CRE form. Note that this may cause the elements to be expanded (depending on 
the setting of RATFAC) which might not always be desired. 

LISTARITH[TRUE] - if FALSE causes any arithmetic operations with lists to 
be suppressed; when TRUE, list-matrix operations are contagious causing lists to 
be converted to matrices yielding a result which is always a matrix. However, 
list-list operations should return lists. 

DETOUT[FALSE] - if TRUE will cause the determinant of a matrix whose 
inverse is computed to be kept outside of the inverse. For this switch to have an 
effect DOALLMX0PS and D0SCMX0PS should be FALSE (see below). Alternatively 
this switch can be given to EV which causes the other two to be set correctly. 

DOALLMXOPS[TRUE] - if TRUE all operations relating to matrices are carried 
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out. If it is FALSE then the setting of the following switches govern which 
operations are performed. 

DOMXMXOPS[FALSE] - if TRUE then all matrix-matrix or matrix-list 
operations are carried out (but not scalar-matrix operations); if this switch is 
FALSE they are not 

DOSCMXOPS[FALSE] - if TRUE then scalar-matrix operations are performed. 

DOSCMXPLUS[FALSE] - if TRUE will cause SCALAR + MATRIX to give a 
matrix answer. 

SCALARMATRIXP[TRUE] - if TRUE causes a square matrix of dimension one 
(when produced as a result of a computation) to be converted to a scalar (i.e. its 
only element). 

SPARSE[FALSE] - if TRUE and if RATMX:TRUE then DETERMINANT will use 
special routines for computing sparse determinants. 



6.4.1 The Dot Operator 

In some applications one would like to work with expressions that contain 
variables which are to behave like matrices (e.g. are non-commutative). The 
variables may be declared to be non-scalar by using the DECLARE function (sect. 
6.12). After the expressions are manipulated into a particular form then perhaps 
actual matrices will be substituted for them. Several options are provided in 
order to control how MACSYMA treats such expressions. (The options are 
checked for and utilized by MACSYMA in the order in which they are presented 
here). 

In the following discussion A, B, and C are any expressions, and S.C is a scalar 
expression (i.e. one free of lists, matrices, and any atoms declared non-scalar). 

DOTASSOCjTRUE] - when TRUE causes (A.B).C to simplify to A.(B.C) 

DOTSCRULES[FALSE] - when TRUE will cause A.SC or SC.A to simplify to 
SC*A and A.(SC*B) to simplify to SC*(A.B) 

DOTCONSTRULES[TRUE] - is similar to DOTSCRULES but with constants 
instead of scalars. 
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DOTEXPTSIMPITRUE1 - when TRIIF r..^ a a ♦- .i_i:i.. *. *^~ 

DOTDISTRIB[FALSE] - if TRUE will cause A.(B*C» to simplify to A.8+A.C 
(Cl) DECLARE([Ml,M2,M3J,N0NSCALAR)t 

(C2 ) ( 1-L*M1 ) . ( 1-UM2) . ( 1-L*M3),D0TC0NSTRULES:TRUE, EXPANO; 
(02) - L N3 ♦ LN2 . LH3 - LH2 ♦ LH1 . L.H3 

- L Ml • U M2 . L M3) ♦ L HI . L H2 - L HI ♦ 1 
<C3) %.DOTSCRULES:TRUE; 

■ * 2 

(D3) - L M3 ♦ L (M2 . M3) - L H2 ♦ L (HI . H3) 

*i 
3 2 

- L (Ml . (M2 . M3)) ♦ L (HI . H2) - L HI ♦ 1 

(C4) RAT(X.L); 

3 
(D4)/R/ - (hi . (M2 . M3)) L ♦ (M2 . H3 ♦ Ml . M3 

2 

♦ HI . M2) L ♦ ( - M3 - M2 - Ml) L ♦ 1 
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6.5 Functions for Rational Expressions 



A rational expression is the quotient of two polynomials. MACSYMA provides 
a special internal representation (called CRE for canonical rational expression form 
- (see 3.1) ) which can be used for rational expressions (and polynomials as 
special cases) and which requires less storage than the general representation. In 
addition CRE manipulations are usually faster. Therefore it may be desirable to 
use these whenever the problem of interest can be expressed largely in terms of 
polynomials or rational expressions. The symbol /R/ following the line label in the 
display of an expression indicates that either the expression is in CRE form or 
that some subexpression of it is. 

CRE form is "contagious" in that any time a CRE expression is added to or 
multiplied by another compatible expression, the result is in CRE form. Thus by 
initially multiplying by RAT(l) one can force his entire calculation to be done in 
CRE form. However, if CRE are mixed into an expression containing general forms 
e.g. S!N(RAT(X**2)) } such that the result is not totally in CRE form, then the result 
is automatically converted into general representation. 

Some functions (e.g. RATSIMP, FACTOR, etc.) use CRE form internally in the 
implementation of their algorithms. This fact however is usually transparent to 
the user. 



RATVARS(Var/, var2, ..., varn) forms its n arguments into a list in which the 
rightmost variable varn will be the main variable of future rational 
expressions in which it occurs, and the other variables will follow in 
sequence. If a variable is missing from the RATVARS list, it will be given 
lower priority than the leftmost variable varl. The arguments to RATVARS 
can be either variables or non-rational functions (e.g. SIN(X)). 
The variable RATVARS is a list of the arguments which have been given to 
this function. 



RATfexp, vl, ..., vn) converts exp to CRE form by expanding and combining all 
terms over a common denominator and cancelling out the greatest common 
divisor of the numerator and denominator as well as converting floating point 
numbers to rational numbers within a tolerance of RATEPSIL0N[2.0E-8]. The 
variables are ordered according to the vl,...,vn as in RATVARS, if these are 
specified. RAT does not generally simplify functions other than + ,-,*,/ , 
and exponentiation to an integer power and it does not deal with equations 
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whereas RATSIMP does handle these cases. Note that atnmc /n,. m ho» =^ 

d at?3 I? rm are n0t the same as the y are in lhe 6 eneral form. Thus 

RAT<X)-X results in RAT(O) which has a different internal representation than 

RATFAC[FALSE] when TRUE invokes a partially factored form for CRE 
rational expressions. During rational operations the expression is maintained 
as fully factored as possible without an actual call to the factor package This 
should always save space and may save some time in some computations. 
The numerator and denominator are still made relatively prime, for example 

RAT((X-2 -ir4/(X*ir2); yields (X-ir4*(X+ir2), 

but the factors within each part may not be relatively prime. 

RATPRINT[TRUE] if FALSE suppresses the printout of the message 
informing the user of the conversion of floating point numbers to rational 
numbers. 

KEEPFLOAT[FALSE] if TRUE prevents floating point numbers from being 
converted to rational numbers. 1 

„ B FT0RAT t F ALSE] controls the conversion of bfloats to rational numbers. 
If BFTORAT:FALSE, RATEPSILON will be used to control the conversion (this 
results in relatively small rational numbers). If BFTORAT:TRUE, the rational 
number generated will accurately represent the bfloat. 

(Also see the RATEXPAND and RATSIMP functions, sec. 6.1.1) 

(Cl) ((X-2*Y)**4/(X**2-4*Y*«2)**2 + l)*(y + A)*(2*Y+X) 
/(4*Y**2+X**2); 

4 
(X - 2 Y) 
(Y ♦ A) (2 Y ♦ X) ( + i) 

2 2 2 

(X - 4 Y ) 
(Dl ) 

Z 2 
4 Y ♦ X 



1. As with all other switches, various MACSYMA algorithms may override the 
setting of this switch if they are unable to operate in that mode. 
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(C2) RAT(%,Y,A,X); 

2 A + 2 Y 

(02)/R/ 

X ♦ 2 Y 



RATDISREPfexp,) changes its argument from CRE form to general form. This is 
sometimes convenient if one wishes to stop the "contagion", or use rational 
functions in non-rational contexts (see the example at the beginning of this 
section). Most CRE functions will work on either CRE or non-CRE 
expressions, but the answers may take different forms. If RATDISREP is 
given a non-CRE for an argument, it returns its argument unchanged. 



TOTALDISREPfexpJ converts every subexpression of exp from CRE to general 
form. If exp is itself in CRE form then this is identical to RATDISREP but if 
not then RATDISREP would return exp unchanged while TOTALDISREP would 
"totally disrep" it. This is useful for ratdisrepping expressions e.g r , equations, 
lists, matrices, etc. which have some subexpressions in CRE form. 



NUMfexp^ obtains the numerator of the rational expression exp. 



DENQMfexp/ returns the denominator of the rational expression exp. 

The above two commands do not alter the internal representations of 
expressions and have the desirable property that for all expressions 
NUM(exp)/DENOM(exp) is the same as exp. This is not true of the following two 
commands which return expressions in CRE form. 



RATNUMERfexp; obtains the numerator of the rational expression exp. If exp is 
in general form then the NUM function should be used instead, unless one 
wishes to get a CRE result. 



RATDENOMfexp,) obtains the denominator of the rational expression exp. If exp 
is in general form then the DENOM function should be used instead, unless 
one wishes to get a CRE result. 
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RATWEIGHTM, wl vn wn> assigns a wei ht of wj , th 

causes a monom.al to be replaced by if its weight exceeds the value of the 
vanable RATWTLVL [FALSE] (for the defauit ^alue FALSE no Tuncitlon 
u^urs,. me weignt of a monomial is the sum of the products of the weieht 

2 xr + w2 tL h , e ter > times iu power - Thus the ™* m <* 3*v!*: 2 : v ^ 

CRE^rnfs o. ^£T ""' "* "*" "•""""^ " '*P™»™"* 

^hJ^?tJ31 ] ^ 1w T a IUt of weieht as »Piments, as does RATWEIGHTO; 
KILL(..,RATWEIGHTS), SAVE(...,RATWEIGHTS) eliminate and save weigh 
assignments ((see 10.3),(see 15.3)). weigni 

(C5) RATWEIGHT(A,l,B.l); 

(D5) [CB, 1], [A, 1]] 

(C6) EXP1:RAT(A+B+1)» 

(C7) %**2; 

2 2 

(07)/R/ B+(2A*2)B*A*2A*1 

(C8) RATWTLVL: It 

(C9) EXP1**2; 

(09)/R/ 2 B ♦ 2 A ♦ 1 

H0R Sor R ne^'r,r ; Wi " """"I "* M ° a res ™e«l representation as in 
h! rZ ■•• „ ' Tl " ar a$ the main variable if il i8 s^fied Wr may also 
mRMFR ,n , WHlCh Ca8e the main V8ri8b,e °' the <** «*•» °< «*P is use^ 
It iT^L ,T S , TESS' $lability if "<"" is t0 be «wmerically evaluated. 



(CI) 1.0E-20*X*2-5.5*X+5.2E20; 

2 
(01) 10E-20 X - 5.5 X* 5.2E+20 

(C2) HORNER(X,X),KEEPFLOAT:TRUE; 

(D2) X (1.0E-20 X - 5.5) ♦ 5.2E+20 

(C3) Dl.Xsl.0E20; 



MACSYMA 6.5 Functions for Rational Expressions 117 



ARITHMETIC OVERFLOW 

(C4) O2,X=1.0E20; 

(04) 6.9999999E+19 



FASTTIMESfpi, p2) multiplies the polynomials pi and p2 by using a special 
algorithm for multiplication of polynomials. They should be multivariate, dense, 
and nearly the same size. Classical multiplication is of order N*M where N 
and M are the degrees. FASTTIMES is of order MAX(N,M)** 1.585. 

The rest of the functions in this section return their results in general 
representation only if all of their principal arguments are in that form, if any 
of their principal arguments are in CRE form then the result is returned in 
CRE form. 



DIVIDEfpi, p2 f varl, ..., varn) computes the quotient and remainder of the 
polynomial pi divided by the polynomial p2. in a main polynomial variable, 
varn. The other variables are as in the RATVARS function. The result is a 
list whose first element is the quotient and whose second element is the 
remainder. 

(Cl) DIVIDE(X+Y,X-Y,X); 

(01) [1, 2 Y] 

(C2) DIVIDE(X+Y,X-Y); 

(02) [ - 1, 2 X] 

(Note that Y is the main variable in C2) 



QUOTIENT (pi, p2, varl, ...) computes the quotient of the polynomial pi divided by 
the polynomial p2. 



REMAINDER^)/, p2, varl, ...) computes the remainder of the polynomial pi divided 
by the polynomial p2. 
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CONTENTYpi, varl, ..., varn) returns a list whose first element is the greatest 
common divisor of the coefficients of the terms of the polynomial pi in the 
variable varn (this is the content) and whose second element is the 
polynomial pi divided by the content 

(Cl) CONTENT(2*X*Y+4*X**2*Y**2,Y); 

(Dl) [2*X, 2*X*Y**2+Y]. 



GCQfpl, p2, varl, ...) computes the greatest common divisor of pi and p2. The 
flag GCD[EZ] determines which algorithm is employed Setting GCD to 
EZ.RED, or MOD selects the EZGCD [M06], reduced, or modular [Brl] 
algorithm, respectively. If GCD:FALSE then GCD(pl,p2,var) will always return 
1 for all x. Many functions (e.g. RATSIMP, FACTOR, etc.) cause gccfs to be 
taken implicitly. For homogeneous polynomials it is recommended, that 
GCD:RED be used. To take the gcd when an algebraic is present, e.g. 
GCD(X"2-2*SQRT(2)*X+2,X~SQRT(2)); , ALGEBRAIC must be TRUE and GCD 
must not be EZ. 



EZGCDfp/, p2, ...) gives a list whose first element is the g.c.d of the polynomials 
pl,p2 t ... and whose remaining elements are the polynomials divided by the 
g.c.d. This always uses the EZGCD algorithm (not recommended for 
homogeneous polynomials). 



MOD(p) converts the polynomial p to a modular representation with respect to the 
current modulus which is the value of the variable MODULUS. 

If MODULUS[FALSE] is set to a positive prime p, then all arithmetic in 
the rational function routines will be done modulo p. That is all integers will 
be reduced to less than p/2 in absolute value (if p=2 then all integers are 
reduced to 1 or 0). This is the so called -balanced" modulus system, e.g. N 
MOD 5 = -2, -1,0,1, or 2. 



RESULTANTfpi, p2, var) computes the resultant of the two polynomials pi and 
p2, eliminating the variable var. The resultant is a determinant of the 
coefficients of var in pi and p2 which equals zero if and oniy if pi and p2 
have a non-constant factor in common. 
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MODRESULT[FALSE] if TRUE causes the modular resultant algorithm to 
be used, otherwise the reduced (which is the default) will be used (see 
[Col]). 

(CI) RESULTANT(A*Y+X^2+1,Y**2+X*Y+B,X); 

4 3 Z 2 

(01) Y ♦ A Y ♦ (2 B ♦■!) Y ♦ B 



RATDIFFfexp, var) differentiates the rational expression exp (which must be a 
ratio of polynomials or a polynomial in the variable var) with respect to var. 
For rational expressions this is much faster than DIFF. The result is left in 
CRE form. However, RATDIFF should not be used on factored CRE forms; use 
DIFF instead for such expressions. 

(Cl) (4*X**3+10*X-ll)/(X**5+5); 

3 

4 X ♦ 10 X - 11 
(01) 

5 
X ♦ 5 

(C2) MODULUS: 31 

(C3) MO0(01); 

2 

X ♦ X - 1 
(03) 

4 3 2 
X ♦ X ♦ X +X+1 

(C4) RATDIFF(Dl.X); 

5 4 3 

X-X-X+X-l 
(D4) 

8 7 5 4 3 
X-X+X-X+X-X+l 
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6.5.1 Algebraic Integers 



An algebraic integer is a solution of a univariate monic polynomial equation 
with integer coefficients. Examples of algebraic integers are 2+3*21, SQRT(7), and 
6^(l/3)-5^(l/7). In addition to the factorization of polynomials over the ring of 
integers with an algebraic integer adjoined, MACSYMA provides simplification of 
expressions involving algebraic integers by representing them in a canonically 
simplified form, in which there are no radicals in the denominators of fractions. 



TELLR AT (poly l,...,polyn) adds to the ring of algebraic integers known to 
MACSYMA, the elements which are the solutions of the univariate, monic 
polynomials polyj (integer coefficients). MACSYMA initially knows about 7.1 
and all roots of integers. TELLRATO returns a list of the polynomials given to 
TELLRAT. To SAVE or KILL all of one's TELLRATs, just do SAVE 
( ...TELLRATS,...) or KILL(...,TELLRATS r ..). To undo a TELLRAT(p(X)), simply do 
TELLRAT(X). 

ALGEBRAIC[FALSE] must be set to TRLE in order for the simplfication of 
algebraic integers to take effect 

RATALGDENOM[TRUE] if TRUE allows rationalization of denominators 
wrt. radicals to take effect. To do this one must use CRE form in algebraic 
mode. 

( C 1 ) ALGEBRAIC : RATALGOENOH : TRUE! 

(C2) RATDIS(E):=RATDISREP(RAT(E))I 

(C3) 10»(1+%I)/(3*(1/3)*XI); 



(D3) 



10 (XI ♦ 1) 

1/3 
3 ♦ XI 



(C4) RATOIS(X); 

2/3 1/3 

(D4) (4 XI ♦ 2) 3 + (4 - 2 XI) 3 - 4 XI - 2 
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(C5) TELLRAT(A*2+A+l)t 

(C6) A/(SQRT(2)+SQRT(3))+1/(A*SQRT(2)-1); 

1 A 
(D6) - + 

SQRT(2) A - 1 SQRT(3) + SQRT(2) 

(C7) RATOIS(X); 

(7 SQRT(3) - 10 SQRT(2) ♦ 2) A - 2 SQRT(2) - 1 
(D7) — 

7 



6.5.2 Functions for Extended Rational Expressions 



An extended rational expression is a truncated power series with rational 
functions for coefficients ( as generated by TAYLOR). The truncation capability 
{KA I WLiUMi,rcAi w ilvl/ descnoea above \see o.a/ is uunZcG uy caiciwcu n">*- 
forms as well as by CRE forms. 



TAYLOR(exp,[varl,ptl,ordl],[var2,pt2,ord2],...) returns a truncated power series 
in the variables van about the points pti, truncated at ordi. For further details 
see 6.7. 

PSEXPAND[FALSE] if TRUE will cause extended rational function 
expressions to display fully expanded (RATEXPAND will also cause this.) If 
FALSE, multivariate expressions will be displayed just as in the rational 
function package. If PSEXPAND:MULTI, then terms with the same total degree 
in the variables are grouped together. 



SRRATfexp>> converts exp from extended rational form to CRE form, i.e. it is like 
RAT(RATDISREP(exp)) although much faster. 



(CI) TAYLORd + X, [X, 0, 3]); 

(Dl)/T/ 1 ♦ X ♦ . . . 
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<C2) l/X; 

<«*)■'*/ 1 - X*X -X ♦ . . . 

<C3) TAYLORd + X ♦ Y + Z, [X, 0. 3], [Y, 1, 2], 
CZ. 2, 1]); 

(03)/T/ 4 ♦ (Z - 2) ♦ (Y - I) ♦ X* . . . 

(C4) l/X; 
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1 Z - 2 1 Z-2 
(04)/T/ ♦(..-♦ ♦..■.) <Y - 1) 

4 16 16 32 

1 3 (Z - 2) 2 

+ <~ - ♦ . . .) (Y - 1) 

64 256 

1 Z-2 1 3 (Z - 2) 
♦ <- --'♦ + ( ♦ . . .) (Y - 1) 

16 32 32 128 

3 3 (Z - 2) 2 

+ ( + ♦ . . .) (Y - 1) ♦ . . •) X 

256 256 

1 3 (Z - 2) 3 3 (Z - 2) 

+ {__ + i- --- + — ------- t . . .; v« " */ 

64 256 256 256 

3 15 (Z - 2) 2 2 

+ ( + . . .) (Y - 1) + . . .) X 

512 2048 

1 Z-2 1 5 (Z - 2) 
+ ( + — - ♦ ( ♦ . . .) (Y - 1) 

256 256 256 1024 

5 15 (Z - 2) 2 3 
+ ( + + . . .) (Y - 1) ♦ . . .) X 

2048 4096 



[6.6] Poisson Series Functions 

A Poisson series is a finite sum where each term has the form p*trig<q) 
where "trig" is either SIN or COS . Usually, p is a polynomial with rational number 
or floating point coefficients, or a general MACSYMA expression. The argument q 
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is a linear combination of no more than 6 variables, whose names are literally U, V, 
W, X, Y, and Z. (These restrictions are not vital, but apparently present no 
difficulty in usual applications. They could be altered easily). 

Conversion to a Poisson series expands all products or powers of sines 
and/or cosines into sums. In order to display the result, it is usually necessary to 
convert an expression in Poisson encoding into general MACSYMA representation 
using the OUTOFPOIS function, or to print it using the PRINTPOIS function. 

POISSIMPM converts A into a Poisson series for A in general representation. 
INTOPOISM^ converts A into a Poisson encoding. 

OUTOFPOIS W converts A from Poisson encoding to general representation. If A 
is not in Poisson form, it will make the conversion, i.e. it will look like the 
result of OUTOFPOIS(INTOPOIS(A)). TNs function is thus a canonical simplifier 
for sums of powers of SIN'S and COS'S of a particular type. 

PRINTPOISW prints a Poisson series in a readable format In common with 
OUTOFPOIS, it will convert A into a Poisson encoding first, if necessary. 

POISTIMES64, B) is functionally identical to INTOPOIS(A*B). 

POISTRIMfl is a reserved function name which (if the user has defined it) gets 
applied during Poisson multiplication. It is a predicate function of 6 arguments 
which are the coefficients of the U, W., Z in a term. Terms for which 
POISTRIM is TRUE (for the coefficients of that term) are eliminated during 
multiplication. 

POISPLUS64, B) is functionally identical to INTOPOIS(A+B). 

PO\SEXPT(A, B) (B a positive integer) is functionally identical to !NTOPOIS(A**B). 
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POISDIFF64, B) differentiates A with respect to B. B must occur only in the trig 
arguments or only in the coefficients. 



POISINT64, B) integrates in a similarly restricted sense (to POISDIFF). Non- 
periodic terms in B are dropped if B is in the trig arguments. 



POISSUBST64, B, C) substitutes A for B in C. C is a Poisson series. 

(1) Where B is a variable U, V, W, X, Y, or Z then A must be an expression 
linear in those variables (e.g. 6*U+4*V). 

(2) Where B is other than those variables, then A must also be free of 
those variables, and furthermore, free of sines or cosines. 



POISSUBST64, B, C, D, N) is a special type of substitution which operates on A 
and B as in type (1) above, but where D is a Poisson series, expands COS(D) 
and SIN(D) to order N so as to provide the result of substituting A+D for B in 
C. The idea is that D is an expansion in terms of a small parameter. For 
example, PQISSUBST(U,V.C0S(V),E,3) results in C0S(U)*(l-E 2 /2> - SIN(U)*(E- 
E 3 /6). 



POISMAPfeer/es, sinfn, cosfn) will map the functions sinfn on the sine terms and 
cosfn on the cosine terms of the poisson series given, sinfn and cosfn are 
functions of two arguments which are a coefficient and a trigonometric part of 
a term in series respectively. 

(CI) PFEFORMAT:TRUEt 

(C2) (2*A A 2-B)*COS(X+2*Y)-(A*B+5)*SIN(U-4*X); 

(D2) - (A B ♦ 5) SIN(U - 4 X) 

2 
+ (2 A - B) C0S(2 Y + X) 

(C3) P0ISEXPT(%,2)« 
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<C4) PRINTPOIS(D3); 

2 
(2 A - B) ( - A B - 5) SIN( - 2 Y - 5 X + U) 

2 
(2 A - B) ( - A B - 5) SIN(2 Y - 3 X ♦ U) 

2 
- 1/2 ( - A B - 5) C0S(2 U - 8 X) 

2 2 2 

1/2 (2 A - B) ♦ 1/2 ( - A • - 5) 

2 2 

1/2 (2 A - B) C0S(4 Y ♦ 2 X) 

(04) DONE 

(C5) POISINT(D3,Y)I 

(C6) POISSIMP(X); 

2 2 

(06) 1/8 (2 A - B) 

2 

SIN(4 Y ♦ 2 X) - 1/2 (2 A - B) ( - A B - 5) 

2 
COS(2 Y - 3 X ♦ U) ♦ 1/2 (2 A - B) ( - A B - 5) 

C0S( -2Y-5X + U) 

(C7) OUTOFPOIS(SIN(Xr5*COS(X) A 5); 

(07) 1/16 SIN(5 X) ♦ 1/16 C0S(5 X) - 5/16 SIN(3 X) 

♦ 5/16 C0S(3 X) ♦ 5/8 SIN(X) + 5/8 COS(X) 

One or two final points: the coefficients in the arguments of the trig 
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functions must fit in a pre-arranged domain. Initially this is set to [-15,16] 
but can be set to [-2 n " rl +l, 2 n ~ 1 ] by the variable POlSLIM[5]. This should 
not be done in the middle of a calculation. Also, it is possible to define the 
coefficient arithmetic to be almost anything. The user (probably in 
conjunction with a LISP-MACSYMA programmer) must define the programs 
needed to add, multiply, substitute, encode and decode the coefficients. The 
encoding for +1 and -1 and a program to test for (zero), completes each 
package. These packages are available for coefficients being CRE form, 
polynomials with floating point coefficients, and polynomials with rational 
number coefficients, in addition to the default general MACSYMA form. 

If all coefficients of trig terms are desired in CRE form, the user should 
L0ADFILE(P0IS3,FASL,DSK,MACSYM) »*<* 

LOADFILE(RATP0l,FASL,DSK,MACSYM). Only those variables on the RATVARS 
list can be used in the coefficients. In many instances this i9 a much more 
efficient technique in terms of speed. 



6.7 Tayior Series 



TAYLORfexp, var, pt, pow) expands the expression exp in a truncated Taylor 
series (or Laurent series, if required) in the variable var around the point pt 
The terms through (var-pf)**pow are generated. If exp is of the form 
f(var)/g(var) and g(var) has no terms up to degree pow then TAYLOR will try 
to expand g(var> up to degree 2*pow. If there are still no non-zero terms 
TAYLOR will keep doubling the degree of the expansion of g(var) until 
reaching pow*2**n where n is the value of the variable TAYL0RDEPTH[3]. 
If MAXTAYORDER[TRUE] is TRUE, then during algebraic manipulation of 
(truncated) Tayior series, TAYLOR will try to retain as many terms as are 
certain to be correct. 
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(Cl) TAYLOR(SQRTU*A*X*SIN(X)),X i 0.3); 



2 2 
(A ♦ 1) X (A ♦ 2 A ♦ 1) X 
(Dl)/R/ 1 ♦ 

2 8 

3 2 3 

(3 A ♦ 9 A ♦ 9 A - 1) X 

♦ ♦ 

48 

(C2) X**2; 

3 

X 
(02)/R/ 1 ♦ (A ♦ 1) X ♦ ... 

6 

<C3) PRO0UCT((X«I*l)**2.5 f I,l,IIIF)/<X«*2*l); 



nv 






/*«»\ 






! f I 
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! t (X 
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i « l 
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X ♦ 


t 





(03) 



(C4) TAYLOR<%.X,0 t 3),ICEEPFLOAT:TRUE; 

2 3 

(D4)/R/ 1.0 ♦ 2.5 X ♦ 3.375 X ♦ 6.5625 X ♦ .. 

(C5) TAYLOR(l/LO6(H-X),X,0,3); 

2 3 
1 1 X X 19 X 
(D5)/R/ •- + -.-- + ... ♦ . . . 

X 2 12 24 720 
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Multivariate Taylor Series Expansions 

For multivariate functions, there are several ways of obtaining Taylor series 
expansions. If the variables are truly independent and all singularities involve 
only one variable at a time then the expansion may be done as follows: 

TAYLORfexp, varl, ptl, ordl, var2, pt2, ord2^J 

or 

TAYL0R(exp,[varl,ptl,ordl],[var2,pt2,ord2],.J 
Naturally the two techniques may be intermixed 

However, if the variables are interdependent or singularities involving some 
of the variables together can occur then the following scheme is to be used: 

t*vi An/*.,- r..~~i wa~o 7 p%f r\»A\ li/hara &_as*h n( r%i anH nrH mas/ foe 

replaced by a list which will correspond to the list of variables, that is, the 
nth items on each of the lists will be associated together. 

The user should be warned that this scheme uses the RATWTLEVEL scheme 
implicitly whenever the variables are expanded to different orders. In this case 
the user must not be trying to use RATWTLEVEL simultaneously. 

Internally this is done in the following manner; for each Xj substitute 

Xj > T n ' Wj. 

Then a term like X 2 Y 3 Z would become 

T 2 n t + 3 n 2 + n 3 w ^ 2 ^3 Wj 

and truncation is done on T. The W variables as well as T are not seen by the 
user. The following are examples of the various modes of Taylor expansions. 

(C5) TAYLOR(SIN(X+Y),X,0,3,Y,0,3); 
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3 2 2 3 2 3 
Y Y X Y X Y X X 
<05)/K/ Y ♦ X ♦ 

* 2 2 12 6 

2 3 
Y X 
♦ — ... ♦ . . # 

12 

<C6) TAYLOR(SIM(X*Y) t [X f Y] f t 3); 

3 2 2 3 

X*3YX+3YX*Y 
(D6)/R/ Y ♦ X - — 



♦ . . . 



<C7) TAYIOR(1/SIN(X*Y),X,Q,3,Y,0,3); 

2 3 
1 V X X X X 
<D7)/R/ « + .-... + . + * . . . 

Y 6 2 « 3 4 
V Y t 

(C8) TAYLOR(1/SIN(X+Y).[X,YJ,0,3); 

1 X ♦ Y 
(06)/R/ ♦ 

X ♦ Y 6 

3 2 2 3 

7X ♦ 21 Y X +21 Y X ♦ 7 Y 

♦ ♦ . . . 

360 

If one wants to handle asymptotic expansions a facility exists to some extent. 
It may be invoked as follows. 



TAYLORfexp, [x,pt,ord,A$YMP]> will give an expansion of exp in negative powers 
of <x-pf). The highest order term will be 



(x-pV'Ori 
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The* ASYMP is a syntactic device and not to be assigned to; for example, one 
types TAYL0R(F(X),[X,0,4,ASYMP]). 

If the user is expanding polynomials he may specify a truncation level of INF in 
which case the expansion will never truncate. 



DEFTAYL0R(7uncf/on, exp) allows the user to define the Taylor series (about 0) 
of an arbitrary function of one variable as exp which may be a polynomial in 
that variable or which may be given implicitly as a power series using the 
SUM function. 



In order to display the information given to DEFTAYLOR one can use 
POWERSERIES(F(X),X,0). (see below). 

(Cl) DEFTAYLOR(F(X),X<oit2«i-SUH(X«*I/(23|oiclj|eI»j|ait2), 

I. 4, INF)); 
(01) [F] 

(C2) TAYLOR(XE**SQRT(F(X)),X v t 4);' 

2 3 4 
X 3073 X 12817 X 
(02)/R/ 1 + X ♦ — + ♦ ♦ . . . 

2 18432 307200 



TAYLORINFOfexpJ returns FALSE if exp is not a Taylor series. Otherwise, a list 
of lists is returned describing the particulars of the Taylor expansion. For 
example, 
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(C3) TAYLOR((1-Y A 2)/(1-X),X,0,3,[Y.A,IMF3); 

2 2 

rniwp/ i . a - 9 a #y .. a* - # v - k\ 

2 2 

♦ (1 - A - 2 A <Y - A) - fY - A) ) X 

2 2 2 

♦ (1 - A - 2 A (Y - A) - <Y - A) ) X 

2 2 3 

♦ (1 - A - 2 A (Y - A) - (Y - A) ) X 

♦ . . . 

<C4) TAYLORINFO(03); 

(04) ICY. A, INF], [X. 0, 3]] 



POWERSERIESfexp, var, pt) generates the general form of the power series 
expansion for exp in the variable var about the point pt (which may be INF 
for infinity). In cases in which POWERSERIES is unable to expand exp the 
TAYLOR function may give the first several terms of the series. 

VERBOSE[FALSE] - if TRUE will cause comments about the progress of 
POWERSERIES to be printed as the execution of it proceeds. 



(C2) VERBOSE: TRUES 

(€3) P0WERSERXES(L0G(SXN(X)/(i~X A 2)),X,e); 

CAN'T EXPAND 

L0€(X - 1) 
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SO WE WILL TRY AGAIN AFTER APPLYING THE RULE: 

d 
/ -- (X - 1) 
[ dX 
LOG(X - 1) * I dX 

] X - 1 
/ 

CAN'T EXPAND 

LOG(SIN(X)) 

SO WE WILL TRY AGAIN AFTER APPLYING THE RULE: 

d 
/ — SIN(X) 
[ dX 

LOG(SIN(X)) = I dX 

] SIN(X) 
/ 

IN FIRST SIMPLIFICATION WE HAVE RETURNEO: 

/ 

C 1 

COT(X) dX - I dX - LOG(X ♦ 1) ♦ LOG<- 1) 

] X - 1 
/ 



IS 12 ZERO OR NONZERO? 
ZERO; 
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TRYING TO DO A RATIONAL FUNCTION EXPANSION OF 



MACSYMA 



X - 1 
USING A SPECIAL RULE FOR EXPRESSIONS OF FORM 

H - N 
(A ♦ C VAR ) 

HERE WE HAVE 

[M ■ 1, A « - 1, C « 1, N « 1] 

INF 

s *« 13 2 13 13 ♦ i 

\ <-D 2 BERN(2 13) LOG(X) X 
<D4) ( > 4 } 

I (2 13)! 13 ♦ 1 

13 s 



INF 

s " 8 12 12 

\ (- 1) X 

* C > — " ) ♦ LOG(-l) 

/ 12 



12 * 1 



6.8 Trigonometric Simplification 



TRiGEXPANDfexp; expands trigonometric and hyperbolic functions of sums of 
angles and of multiple angles occurring in exp For best results, exp should 
be expanded. To enhance user control of simplification, this function expands 



MACSYMA 6.8 Trigonometric Simplification 1 35 

only one level at a time, expanding sums of angles or multiple angles. To 
obtain full expansion into sines and cosines immediately, set the switch 
TRIGEXPAND:TRUE. 

TRIGEXPAND[FALSE] if TRUE causes expansion of all expressions 
containing SINs and COSs occurring subsequently. 

HALFANGLES[FALSE] - if TRUE causes haK-angles to be simplified away. 

(Cl) X+SIN(3*X)/SIN(X),TRIGEXPAND=TRUE, EXPAND; 

2 2 

(Dl) - SIN (X) ♦ 3 COS (X) ♦ X 

(C2) TRIGEXPAND(SIN(10*X+Y)); 

(D2) COS(10 X) SIN(Y) ♦ SIN(10 X) COS(Y) 



TRIGREDUCEfexp, var) combines products and powers of trigonometric and 
hyperbolic SINs and COSs of var into those of multiples of var. It also tries to 

miiiiidv^ mcijc iuitv.iivi!9 vYiicii mcjr wwuuf iii uciiOfnincuGrs. u var is Grniu6u 

then all variables in exp are used. Also see the POISSIMP function (6.6). 

(C4) TRIGREDUCE(Dl); 

(04) 2 C0S(2 X) ♦ X ♦ 1 



The trigonometric simplification routines will use declared information in 
some simple cases. Declarations about variables (see 10.8) are used as 
follows, e.g. 



(C5) DECLARER, INTEGER, E, EVEN, 0, O0D)t 
(C6) SIN(X + (E ♦ 1/2)*XPI)I 
(D6) COS(X) 

(C7) SIN(X + (0 ♦ 1/2) XPI); 

(07) - C0S(X) 
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There are a number of ways the user may also explicitly invoke identities 
such as sin^x) + cos^x) - 1. The simplest method is substitution. 



<C8) Dl; 

2 2 

(08) - SIM (X) ♦ 3 COS (X) ♦ X 

<C9) %.SIN(Xr2«l-C0S(Xr2; 

2 
<*>$> 4 COS (X) ♦ X - 1 



Often one wishes to recognize that sin^x) can be transformed using the same 
rule. For this one needs the added power of RATSUBST. 



(CIO) RATSUBST(l-COS(X) A 2.SIN(Xr2 t SIM(Xr4); 

4 2 

<D10) COS (X) - 2 COS (X) ♦ 1 



In general RATSUBST will perform a RATSIMP (and thus an expansion) as well 
as apply the substitution. One can similarly use the LETSIMP and DEFRULE 
commands together with additional declarations to define more intricate rules. 

Although not as powerful as RATSUBST, the TELLSIMP command enables the 
automatic application of a rule. 



(Cll) TELLSIHP(SIII(Xr2 f l-C0S(Xr2)t 

(C12) (SIN(X)*ir2; 

2 

< D **) (SI*(X) ♦ 1) 

(C13) EXPAND(X); 

2 

(013) z SIN(X) - COS (X) ♦ 2 

(C14) SIN(Xr2; 
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2 

(D14) 1 - COS (X) 



6.9 Laplace Transforms 



LAPLACEfexp, ovar, War) takes the Laplace transform of exp with respect to the 
variable ovar and transform parameter tvar. Exp may only involve the 
functions EXP, LOG, SIN, COS, SINH, COSH, and ERF. It may also be a linear, 
constant coefficient differential equation in which case ATVALUE (see 6.2.2) 
of the dependent variable will.be used. These may be supplied either before 
or after the transform is taken. Since the initial conditions must be specified 
at zero, if one has boundary conditions imposed elsewhere he can impose 
these on the general solution and eliminate the constants by solving the 
general solution for them and substituting their values back, exp may also 
involve convolution integrals. Functional relationships must be explicitly 
represented in order for LAPLACE to work properly. That is, if F depends on 
X and Y it mjst be written as F(X,Y) wherever F occurs as in 
LAPLACE('DIFF(F(X,Y),X),X,S). 

(CI) LAPLACE(%E**(2*T+A)*SIN(T)*T,T,S); 

A 
2 XE (S - 2) 

(01) 

2 2 

((S - 2) +1) 



(C2) LAPLACE(DELTA(T-A)*SIN(B*T),T,S); 

Is A positive, negative or zero? 

POS; 

-AS 
(02) SIN(A B) %E 
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ILTfexp, Ivar, ovar) takes the inverse Laplace transform of exp with respect to 
Ivar and parameter ovar. exp must be a ratio of polynomials whose 
denominator has only linear and quadratic factors. By using the functions 
LAPLACE and ILT together with the SOLVE or LINSOLVE functions the user can 
solve a single differential or convolution integral equation or a set of them. 

(Cl) aNTEGRATE(SINH(A*X)*F(T-X),X,0,T)+B»F(T)=T«*2; 

T 
/ 

[ 2 

(Dl) I (SINH(A X) F(T - X)) OX ♦ B F(T) * T 

]. 
/ 


<C2) LAPLACE(X,T,S); 

A LAPLACE(F(T), T, S) 2 

< D2 > ♦ B LAPLACE(F(T), T, S) = — 

2 2 3 

S - A S 

(C3) LINS0LVE([X],[aAPLACE(F(T),T,S)3); 
SOLUTION 

2 2 
2 S - 2 A 
(E3) LAPLACE(F(T), T, S) * - 

5 2 3 

B S ♦ (A - A B) S 

(03) [E3] 

<C4) ILT(E3,S,T); 

Is A B (A B - 1) positive, negative, or zero? 

POS; 
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2 
SQRT(A) SQRT(A B - B) T 

2 COSH(- ) 

B 

(D4) F(T) = 

A 

2 

AT 2 

+ + — - — ........ — 

A B - 1 3 2 2 

A B - 2 A B + A 



Laplace Transforms of Special Functions 

The following function for taking Laplace transforms of Special Functions is 
available in MACSYMA. The user must type LOADFILE(SPECFN,USP,DSK,SHARE); 
to load in the special routines. Since the latter take up a great deal of space, it 
is recommended that these computations be carried out in a fresh MACSYMA. 



LAPINTf exp,ovar; takes the Laplace transform of exp with respect to the variable 
over, exp may involve 

1) Special Functions of linear or quadratic argument multiplied by 

a) arbitrary powers of the argument, or 

b) trigonometric and exponential functions of linear argument 

2) Products of two Special Functions of linear or quadratic argument 
taken from only one of the following groups: 

a) Any kind of Bessel, Modified Bessel, or Hankel functions, 

b) Orthogonal polynomials, 

c) Confluent Hypergeometrlc Functions 

In this second category, factors of type la or lb are also permitted 

The basic method is to rewrite the expression in terms of Generalized 
Hypergeometrlc Functions (GHF), apply a general formula for taking the 
Laplace transform of GHPs, and then, if possible, present the result In terms 
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of elementary functions or "common" Special Functions. For further details, 
see Symbolic Laplace Transforms of Special Functions [AvJ 

(Cl) T /v (l/2)*GAMMAINC0MPLETE(l/2,/UiET)*%E A {-!>*T); 

1 - P T 

< D1 > GAMMAINCOMPLETE(-, A T) SORT(T) XE 

2 
(C2) LAPINT(X.T); 

XPI 2 

(02) 

3/2 A 3/2 3/2 A 3/2 
2 (P ♦ A) (1 ) (p ♦ A) (1 ) 

P ♦ A p ♦ A 

<C3) T-(1/2)*J(13(2*A A <1/2)*T-(1/2))«XE^(-P«T); 

- P T . 
< D3 > J (2 SQRT(A) SQRT(T)) SQRT(T) XE 

1 

(C4) LAPINT(X.T); 

- A/P 

SQRT(A) XE 
(04) 



2 
P 



<C5) T~2*0[1](A*T)*XE A (-P*T); 



2 - P T 
(D5) (A T) T XE 

1 
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(C6) LAPINT(X,T); 

3 A 
(06) 

2 
A 5/2 4 

<-- ♦ 1) P 

2 
P 
(C7) T~(3/2)*Y[i](A»T)*XE*(-T); 

3/2 - T 
(°7) Y (A T) T XE 

1 
(C8) LAPINT(X,T); 

XI 1 3/4 

15 XI SQRT(2) P (- --) ( 1) 

- 2, 1/2 A 2 

A ♦ 1 
(08) .- 

2 2 2 2 1/4 

8 SQRT(XPI) (A + 1) ((A ♦ 1) - 1) 

6.10 Combinatorial Functions 



MINFACTORIALfexp) examines exp for occurrences of two factorials which differ 
by an integer. It then turns one into a polynomial times the other. 

(CI) N!/(N+1)!; 

N! 

(01) 

(N ♦ 1)! 

(C2) MINFACTORIAL(X); 

1 

(02) 

N ♦ 1 
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FACTCOMBfexp; tries to combine the coefficients of factorials in exp with the 
factorials themselves by converting, for example, (N+1)*N! into (N+l)!. 

SUMSPLITFACTfTRUE] if set to FALSE will cause MINFACTORIAL to be 
applied after a FACTCOMB. 



(Cl) (N+irB*NrB; 
(Dl) 


B B 

(N ♦ 1) M! 


(C2) FACTCOHB(X); 
(01) 


B 



MAKEFACTfexp; transforms occurrences of binomial.gamma, and beta functions in 
exp to factorials. 



MAKEGAMMAfexp^ transforms occurrences of binomial.factorial, and beta functions 
in exp to gamma functions. 



BERNPOLYfV, n) generates the nth Bernoulli polynomial in the variable v. 
6.11 Continued Fractions 



CF(exp) converts exp into a continued fraction, exp is an expression composed 
of arithmetic operators and lists which represent continued fractions. A 
continued fraction a+l/(b+l/(c+...)) is represented by the list [a,b,c,...]. a,b,c,.. 
must be integers. Exp may also involve SQRT(n) where n is an integer. In 
this case CF will give as many terms of the continued fraction as the value of 
the variable CFLENGTH[1] times the period. Thus the default is to give one 
period 
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CFDISREP(7/stf converts the continued fraction represented by list into general 
representation. 

(Cl) CF([l,2,-3Ml,-2,ll); 

(01) [1, 1, 1, 2] 

(C2) CFDISREP(X); 

1 

(02) 1 ♦ 

1 
1 + 

1 

1 ♦ - 

2 



CFEXPANDfr/ 1 gives a matrix of the numerators and denominators of the next- to- 
last and last convergents of the continued fraction x. 

(Cl) (CFLENGTH:4, CF(SQRT(3)); 

(01) [1. 1. 2, 1, 2, 1, 2. 1, 2] 

(C2) CFEXPAND(X); 

[265 97] 

(02) [ ] 

[153 56] 

(C3) D2[1,2]/D2[2,2].NUMER; 

(03) 1.73214285 



6.12 Number-Theoretic Functions 



PRIMER gives the Mh prime. MAXPRIME[489318] is the largest number 
accepted as argument. 
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DIVSUMCn,*; adds up all the factors of n raised to the *th power. If only one 
argument is given then k is assumed to be 1. 



TOTIENW is the number of integers less than n which are relatively prime to n 
Also n - DIVSUM(n,0) + 1. 

JACQBl(p,q) is the Jacobi symbol of p and q. 

QUNIT^ gives the principal unit of the real quadratic number field SQRT(n) 
where n is an integer, i.e. the element whose norm is unity. This amounts to 
solving Pell's equation A**2-mB**2=l. 

(Cl) QUNIT(17); 

(01) SQRT(17)*4 

<C2) EXPAND(X*(SQRT(17)-4)); 

(02) i 
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7 Declaring and Using Mathematical Information 



The commands in this chapter deal with the communication, use, and 
manipulation of mathematical information about objects and functions in MACSYMA. 
Taken as a whole, this information comprises MACSYMA's relational data base. 
Facts take the form of either "predicates" or "features". A predicate is a well- 
formed formula consisting of a relation and its arguments, e.g. A>B, or is a 
composition of predicates using the logical operators NOT, AND, and OR. 
Alternatively, certain facts about mathematical objects and functions can be 
expressed more naturally as "features", i.e. unary predicates. For example, one 
can say that a certain constant is an INTEGER or that a function is INCREASING. 
Any feature, e.g. the linearity of F, can also be expressed as a predicate via the 
relation KIND, as in KIND(F,LINEAR). 



7. 1 Declaring and Assuming 



The predicates and features communicated to MACSYMA with the ASSUME 
and DECLARE commands may be tested with iS and FEATUREP and removed with 
FORGET and REMOVE. The facts in the relational data base are used by the 
simplifier and several commands, like SIGN, the IF statement, and INTEGRATE 
(certain integrations require sign information). MACSYMA has a rudimentary 
inference capability enabling limited deductions from the data base. It excels at 
taxonomic deductions, e.g. KIND(N,EVEN) implies KIND(N,INTEGER), and simple 
expression comparisons, e.g. X<0 and KIND(N,EVEN) imply Y^+X^>0. The only sort 
of inequality information used by the inference mechanism at the moment &re 
relations between variables and other variables and numbers. 

The operator "=" is a total relation that holds between two expressions if 
and only if the expressions are syntactically identical. It is not a mathematical 
comparison. Thus, IS((X+1)^2=X^2+2*X+1) would return FALSE. The relation 
EQUAL, on the other hand, is a mathematical comparison of its two arguments. A 
predicate involving EQUAL is true if and only if its arguments are mathematically 
equivalent in light of the current data base. Thus, IS(EQUAL<(X+ir2,X^2+2*X+l)) 
would return TRUE. The operators M >", ">=", "<", and "<=" are also mathematical 
comparisons. 

MACSYMA currently recognizes and uses the following features of objects: 
EVEN, ODD, INTEGER, RATIONAL, IRRATIONAL, REAL, IMAGINARY, and COMPLEX. 
The useful features of functions include: INCREASING, DECREASING, ODDFUN (odd 
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function), EVENFUN (even (unction), COMMUTATIVE (or SYMMFTRin 
ANTISYMMETRIC, ASSOCIATIVE. "'*"vt tor SYMMETRIC), 

ASSUMEfprerf; pre d2, ...) first checks the specified predicates for redundancy 
and °^ !T*. W i l \!!" ° Urrent daU baSe " the Plates are consistent 
rrlnTT , ' h ? L are mkM t0 lhe data ba8e > if inconsistent or 

^h?,!, ' n °^r.' 8 ^ wa ASSUME returns a li8t wh ° 8e e"^ie S are the 
fSSSSSnS?^ t0 ^ uf 8la b8$e ,nd the atoms REDUNDANT or 
L^gurtenU * 8ppl,Cable - ASSUME also ^P' 8 li8t8 «>' Predicates as 

r0H< tn < ^\ P ^ ed2 ' "! removes th * 8peci,ied Predicates from the data base. 
Note that it does not guarantee that equivalent facts are removed. FORGET 
also accepts lists of predicates as arguments. 

^MEXKIN^FJNCREASING)). The /end ? may'Xt HsuT^ts ir 

REMOVER, «. a3/2, ...; removes each feature fi from the corresponding object 
*• The ai and fi may also be lists of object* or features. 

ISfpredl attempts to determine whether the specified predicate is provable from 
the facts in the current data base. IS returns TRUE if the predicate is true 

FALSFiMM*^ *! V ^ tabl ? COnsi8tent with the data ba8e a "° returns 
FALSE if it is false for all such values. Otherwise, its action depends on the 

P R E n™p^ th ™^ PREDERTORtTRUE l ,S wr8 «* " ^e value ol 
PREDERROR is TRUE and returns UNKNOWN if PREDERROR is FALSE. 

FEATUREPfa/; attempts to determine whether the object a has the feature f on 

false"" lhe current data ba$e- " "* ft returns TRUE « e,8e 

(Cl) DECLARE(J,EVEN)t 
<«) FEATUREPf J, INTEGER); 
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(02) TRUE 



$\GN(exp) attempts to determine the sign of its specified expression on the basis 
of the facts in the current data base. It returns one of the following answers: 
POS (positive), NEG (negative), ZERO, PZ (positive or zero), NZ (negative or 
zero), PN (positive or negative), or PNZ (positive, negative, or zero, i.e. 
nothing known). 

(C3) ASSUME(A>=B,B>=C,C>=D,D>=A); 

(° 3 ) [A >= B, B >: C, C >= D, D >r A] 

(C4) SIGN(B-C); 

(04) ZERO 

(C5) DECLARER, INTEGER, L,0DD,F, INCREASING)* 

(C6) ASSUME (X>0); 

(06) [X > 0] 

(C7) F(X+3*Y~(L+24*K+1))-F(0); 

L + 24 K + 1 
< D7 ) F(3 Y + X) - F(0) 

(C8) SIGN(X); 

(08) POS 



ASKSIGNfexp; first attempts to determine whether the specified expression is 
positive, negative, or zero. If it cannot, it asks the user the necessary 
questions to complete its deduction. 1 The user's answer is recorded in the 
data base for the duration of the current computation (one H C-line M ) The 
value of ASKSIGN is one of POS, NEG, or ZERO. 

The following function, when applicable, gives the user relational information. 
However, it does NOT use the data base. 



1. If the user wishes to look at the expression more closely before replying, the 
variable ASKEXP is set to it. Typing control-A results in a MACSYMA break (see 
4); the user may now analyze the expression in order to give an appropriate 
answer. 
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ZEROEQUW/ (exp,var) tests whether the expression exp in the single variable var 
is equivalent to zero, it returns either TRUE, FALSE, or DONTKNOW. For 
example ZER0EQUIV(SIN(2*X) - 2*SIN(X)*C0S(X),X) returns TRUE and 
ZER0EQUIV(7oE"X+X,X) returns FALSE. On the other hand 
ZEROEQUIV<LOG(A*B) - LOG(A) - LOG(B),A) will return DONTKNOW because 
of the presence of an extra variable. The restrictions are: 

(1) Do not use functions that MACSYMA does not know how to differentiate 
and evaluate. 

(2) If the expression has poles on the real line, there may be errors in the 
result (but this is unlikely to occur). 

(3) If the expression contains functions which are not solutions to first order 
differential equations there may be incorrect results. 

(4) The algorithm uses floating-point evaluation at randomly chosen points 
using a corresponding "epsilon" for carefully selected subexpressions. This is 
always somewhat hazardous, although the algorithm tries to minimize the 
potential for error. 



7.2 Contexts 



The context mechanism makes it possible for a user to bind together and 
name a selected portion of his data base, called a context Once this is done, the 
user can have MACSYMA assume or forget large numbers of facts merely by 
activating or deactivating their context. Any atom can be a context, and the facts 
contained in that context will be retained in storage until the user destroys them 
individually by using FORGET or destroys them as a whole by using KILL to 
destroy the context to which they belong. 



F ACTS(context) returns a list of the facts in the specified context 



ACTIVATEfconf/, cont2, ...) causes the facts in the specified contexts contk to be 
added to the current data base. 
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DEACTIVATEfconf/, cont2, ...) causes the facts in the specified contexts contk to 
be removed from the current data base, unless specified by some other 
active context. 

CONTEXT[GLOBALJ Whenever a user assumes a new fact, it is placed in the 
context named as the current value of the variable CONTEXT. Similarly, 
FORGET references the current value of CONTEXT. To add or delete a fact 
from a different context, one must bind CONTEXT to the intended context and 
then perform the desired additions or deletions. The context specified by the 
value of CONTEXT is automatically activated. AH of MACSYMA's built-in 
relational knowledge is contained in the default context GLOBAL 

CONTEXTS[[]] is a list of the currently active contexts, not including the 
value of CONTEXT. 

(C9) CONTEXT: CON It 

(CIO) DECLARER, INTEGER)! 



(Oil) FEATUREP(M, INTEGER); 



I #v t \ \ 

\uiif 



TRUE 



(C12) CONTEXT :C0N2* 



(C13) FEATUREP(M, INTEGER); 
(D13) 



FALSE 



(C14) DECLARE(N, INTEGER); 
(D14) 



DONE 



(C15) CONTEXTiCONIS 



(C16) FEATUREP(M, INTEGER); 
(D16) 



TRUE 



(C17) FEATUREP(N, INTEGER); 
(D17) 



FALSE 



(C18) ACTIVATE(C0N2)S 



(C19) FEATUREP(N, INTEGER); 
(D19) 



TRUE 
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(C13) CONTEXTS; 

< D13 > [COM2] 

LOCAUa/, a2, ...) causes the external facts about the objects al, a2, ... to be 
forgotten for the duration of the enclosing BLOCK, independent of context. 
Any facts assumed about al, a2, ... within the BLOCK containing the LOCAL 
will be forgotten upon exit, again independent of context. 

(C14) DECLARER, INTE6ER)t 

(C15) BLOCK(LOCAL(P),PRINT(FEATUREP(P,INTE6ER)),ASSUME(P,IRRATIONAL))S 
FALSE 

(C16) FEATUREP( P. INTEGER); 

<D16) TRUE 

(C17) FEATUREP(P, IRRATIONAL); 

(017) FALSE 
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8 List Handling and LISP-like functions 



APPLY (function, list) gives the result of applying the function to the list of its 
arguments. This is useful when it is desired to compute the arguments to a 
function before applying that function. For example, if L is the list [1, 5, 
-10.2, 4, 31 then APPLY(MIN,L) gives -10.2. APPLY is also useful when 
calling functions which do not have their arguments evaluated if it is desired 
to cause evaluation of them. For example, if FILESPEC is a variable bound to 
the list [TEST, CASE] then APPLY(CLOSEFILE,FILESPEC) is equivalent to 
CLOSEFILE(TEST,CASE). In general the first argument to APPLY should be 
preceded by a ' to to make it evaluate to itself. Since some atomic variables 
have the same name as certain functions the values of the variable would be 
used rather than the function because APPLY has its first argument evaluated 
as well as its second. 



FUNMbKE(name,[argl,...,argn]) returns namei argl y ..,argn) without calling the 
function name. 



ARRAYM AKE(name,[il,i2,..J) returns name[il,i2 t ...l 



MkP(fn, expl, exp2, ...) returns an expression whose leading operator is the same 
as that of the expi but whose subparts are the results of applying fn to the 
corresponding subparts of the expi. Fn is either the name of a function of n 
arguments (where n is the number of expi) or is a LAMBDA form of n 
arguments. 

MAPERR0R[TRUE] - if FALSE will cause all of the mapping functions to 
(1) stop when they finish going down the shortest expi if not all of the expi 
are of the same length and (2) apply fn to [expl, exp2,.;.] if the expi are not 
all the same type of object. If MAPERROR is TRUE then an error message will 
be given in the above two" instances. 

One of the uses of this function is to MAP a function (e.g. PARTFRAC) 
onto each term of a very large expression where it ordinarily wouldn't be 
possible to use the function on the entire expression due to an exhaustion of 
list storage space in the course of the computation. 
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(Cl) MAP(F,X+A*Y+B*Z); 

< D1 > F(B Z) + F(A Y) ♦ F(X) 

(C2) MAP(LAMBDA([U].PARTFRAC(U,X)),X/(X*3+4*X A 2*5*X+2)); 

i X 

(02) X (--— ----- ) 

X ♦ 2 2 

(X* 1) 

(C3) MAP(RATSIMP, X/(X**2+X)+(Y**2*Y)/Y); 

1 

(03) Y ♦ ♦ 1 

X ♦ 1 

(C4) MAP(-=",[A.B].[-.5, 3.2.5]); 

MAP IS TRUNCATING. 

<M) [A s -.5, B « 31 



MAPATOMCexpr; js TRUE if and only if expr is treated by the MAPping routines a 
as an "atom", a unit. "Mapatoms" are atoms, numbers (including rational 
numbers), and subscripted variables. 

MAPLIS7Y/H expl, exp2, ...) yields a list of the applications of fn to the parts of 
the expi This differs from MAP(/Hexpi,exp3...) which returns an expression 
with the same main operator as expi has (except for simplifications and the 
case where MAP does an APPLY). Fn is of the same form as in MAP. 

FULLMAPfYn, expl, ...) is similar to MAP but it will keep mapping down all 
subexpressions until the main operators are no longer the same. 
The user should be aware that FULLMAP is used by the MACSYMA simplifier 
for certain matrix manipulationsj thus, the user might see an error message 
concerning FULLMAP even though FULLMAP was not explicitly called by the 
user. 

(Cl) A+B*CS 

(C2) FULLMAP(G,%>; 

CM) 6(B) G(C) ♦ 6(A) 
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(C3) MAP(G.Dl); 

(03) 6(B C) + 6(A) 



FULLMAPU/n, Ijstl, ...) is similar to FULLMAP but it only maps onto lists and 
matrices 

(Cl) FULLMAPL("+\[3,[4,5]L[[A,1],[0,-1.5]]); 

(Dl) [[A ♦ 3, 4], [4, 3.5]] 



SCMMkP(function,exp) recursively applies function to exp. This is most useful 
when "complete" factorization is desired, for example: 



(Cl) EXP:(A A 2+2*A+1)*Y + X A 21 

(C2) SCANMAP(FACTOR,EXP); 

2 2 

(D2) (A ♦ 1) Y ♦ X 



Note the way in which SCANMAP applies the given function FACTOR to 
the constituent subexpressions of exp, if another form of exp is presented to 
SCANMAP then the result may be different. Thus, D2 is not recovered when 
SCANMAP is applied to the expanded form of exp: 



(C3) SCANMAP(FACTOR,EXPAND(EXP)); 

2 2 

(D3) A Y + 2AY + Y + X 

Here is another example of the way in which SCANMAP recursively 
applies a given function to all subexpressions, including exponents: 

(C4) EXPR : U*v~(A*X+B) + Cl 

(C5) SCANMAP('F, EXPR); 



1 54 8 List Handling and USP-like functions MACSYMA 



F(F(F(A) F(X)) ♦ F(B)) 
(D5) F(F(F(U) F(F(V) )) ♦ F(C )) 



APPENOOistl, Iist2, .J returns a single list of the elements of listl followed by 
the elements of Ii$t2 r .. 

(CI) APPEN0([Y*X,0 t -3.2],[2.5E20,X]); 
(°n CY*X, 0, -3.2. 2.5E20, X] 



CONSfexp, fist) returns a new list constructed of the element exp as its first 
element, followed by the elements of list 



ENDCONSfexp, list) returns a new list consisting of the elements of list followed 
by exp. 



MEMBERfexp, list) returns TRUE if exp occurs as a member of list (not within a 
member). Otherwise FALSE is returned 



REVERSE(7/sf; reverses the order of the members of list (not the members 
themselves). 

The functions FIRST, REST, LAST, DELETE, LENGTH (6.Z3) also work on lists. 



Examples 

(Cl) UNION(X f Y): = IF X * [ ] THEN Y ELSE 

IF MEHBER(T:FIRST(X),Y) THEN UNION(REST(X),Y) 
ELSE CONS(T s UNION(REST(XhY)i 

(C2) UNION([A,B,l,l/2,X*«23 f C-X«»2 f A > Y,l/2]); 

2 2 1 

< D2 > [X , 1, B t - X , A, Y, -] 

2 
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In this example T is assigned the value of FIRST(X) in the call to MEMBER 
and is referenced later in CONS(T,UNION{...)). 

(C3) BERNP0LY(X,5); 

4 3 
5 5 X 5 X X 
(D3) X + 

2 3 6 

(C4) MAPLIST(NUMFACTOR,%); 

5 5 1 
(04) [1, --.-,- -] 



(C5) APPLY(MIN.X); 
(D5) 



2 3 6 

5 
2 



[8. 1 ] Property Specification Functions 



The functions in this section are used to specify properties for atomic 
variables. A property is a piece of information which may be utilized during the 
user's session with MACSYMA. MODEDECLARE (sec. 10.8) is one example 
of a property specification function. Also, the subsequent section deals with 
functions for pattern matching and includes the function MATCHDECLARE. As 
these are somewhat complicated they are described in other sections. However, 
along with DECLARE (see below) and other functions, they all perform the task of 
setting up information which is used later. 

For most types of properties there exists a name which is an indicator of that 
property. For example the command GRADEF(F(X),SIN(X**2)); causes F to receive 
a "gradef" property of LAMBDA([X],SIN(X**2)). (The indicator is GRADEF and the 
property is the lambda expression). 

The presence of some properties is signified merely by the presence of the 
indicator and requires no additional information. These indicators are known as 
flags. For example 7.1 has associated with it the flag CONSTANT. We can also 
speak of "constant" as being a property of 7.1. 
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There are three principal operations which are needed by the user in dealing 
with properties. He must be able to set up the property, to display it, and to 
remove it. Also he may sometimes want to know what properties he set up in his 
.w.^i^cuvin. i nere are several iisis \ Known as information lists) which contain all 
of the atoms that possess a particular property. Moreover, the value of the 
variable INFOLISTS is a list of the names of all of the information lists in 
MACSYMA. These are: 

LABELS - all bound C,D, and E labels. 

VALUES - all bound atoms (set up by : , :: , or functional binding). 

FUNCTIONS - all user defined functions (set up by f(x):=.J. 

ARRAYS - declared and undeclared arrays (set up by : , ;: , or a[xj=...) 

MYOPTIONS - all options ever reset by the user (whether or not they get 
reset to their default value). 

RULES - user defined pattern matching and simplification rules (set up by 
TELLSIMP, TELLSIMPAFTER, DEFMATCH, or, DEFRULL) 

ALIASES - atoms which have a user defined alias (set up by the ALIAS, 
ORDERGREAT, ORDERLESS functions or by DECLAREing the atom a NOUN). 

DEPENDENCIES - atoms which have functional dependencies (set up by the 
DEPENDS or GRADEF functions). 

GRADEFS - functions which have user defined derivatives (set up by the 
GRADEF function). H J 

PROPS - atoms which have any property other than those mentioned above, 
such as atvalues, matchdeclares, etc as well as properties specified in the 
DECLARE function. 

In addition to these information lists similar lists may be generated by the 
function PROPVARSfprop; which yields a list of those atoms on the PROPS list 
which have the property indicated by prop. Thus PROPVARS(ATVALUE) will yield 
a list of atoms which have atvalues. 
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DECLARE^/, fl, a2, f2, ...) gives the atom ai the flag fi. The afs and fPs may also 
be lists of atoms and flags respectively in which case each of the atoms gets 
all of the properties. The possible flags and their meanings are: 

CONSTANT - makes ai a constant as is %PL 

NONSCALAR - makes ai behave as does a list or matrix with respect to 
the dot operator, (see 6.4.1) 

NOUN - makes the function ai a noun so that it won't be evaluated 
automatically, (see 3.2) 

ALPHABETIC - adds ai to MACSYMA's alphabet (initially A-Z,7.). Thus, 
DECLARE( M J\ALPHABETIC) enables NEWJ/ALUE to be used as a name. 

EVFUN - makes ai known to the EV function so that it will get applied if 
its name is mentioned, initial evfuns are FACTOR, TRiGEXPAND, 
TRIGREDUCE, BFLOAT, RATSIMP, RATEXPAND, RADCAN, and 
LOGCONTRACT. 

EVFLAG - makes ai known to the EV function so that it will be bound to 
TRUE during the execution of EV if it is mentioned. Initial evflags are FLOAT, 
PRED, SIMP, NUMER, DETOUT, EXPONENTIALIZE, DEMOIVRE, KEEPFLOAT, 
LISTARITH, TRIGEXPAND, SIMPSUM, ALGEBRAIC, RATALGDENOM, 
FACTORFLAG, and LOGEXPAND. 

BINDTEST - causes ai to signal an error if it ever is used in a 
computation unbound (see Chapter 1 9). 

ARRAYINFOfaj returns a list of information about the array a. For hashed arrays 
it returns a list of "HASHED", the number of subscripts, and the subscripts of 
every element which has a value. For declared arrays it returns a list of 
"DECLARED", the number of subscripts, and the bounds that were given the 
the ARRAY function when it was called on a. 

(Cl) B[l,X]:lt 
(C2) ARRAY(F,2,3)S 
(C3) ARRAYINFO(B); 



1 58 8l1 Functions for Handling MACSYMA Properties MACSYMA 

< D3 > [HASHED, 2. [1, X]] 

(C4) ARRAYINFO(F); 

(D4) TDFriARFn 9 to in 

PR °^,h T !K S ^ Wi " yieW a " St Sh0Wing the names of 8 " lhe Properties associated 
wun me atom a. 

PRINTPROPS^ /> will display .the property with the indicator / associated with the 
atom a. a may also be a list of atoms or the atom ALL in wNch case all of the 
atoms with the given property will be used For examole 
m^T? .""WHO* !• ^r properties that ca „lt' 
MATCHDECLARE. '* f0f A ™ ALU ^ AT M <*AD.GRADEF, and 

REMOVEfa/, p/ ( «g P 2, „j removes the property pi from the atom ai. Ai and pi 

Mnnmrn !pp , 8S ^ ith DEC , LARE " may be "V P r °P ertv e 8- FUNCTION, 
SvJ^™ m,k % ,t f ma y. al f° 1 be TR ANSFUN implying that the translated 
hll. ?h MAniv e l A UnCt '° n ,S t0 be removed This is useful " one wishes to 
f-Ic, ?, MACSYMA v ^sion of the function executed rather than the 
translated version. P, may also be OP or OPERATOR to remove a syntax 
i C nH T °" g,ven . to a/ < see Appendix II). If ai is "ALL" then the property 
indicated by p, is removed from all atoms which have it. Unlike the more 

rImriH n p™ V nwr f r ti0nS . .^WALUE, REMARRAY, REMFUNCTION, and 
if Zyf reTr 8 V W. "* "*" "" ' "^ ""^ h —^ 

8. 1 .2 Functions for Handling Users' Properties 



PUT l.lh. * asSOciates with the alom • «» Property p with the indicator /. This 
cnaoics in© user Co sive an atom anv arbitrary Dronprfv 

QPUTYa, p, # is similar to PUT but it doesn't have its arguments evaluated. 



MACSYMA 
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GETfa, i) retrieves the user property indicated by / associated with atom a or 
returns FALSE if a doesn't have property /. 

(CI) PUT(%E,TRANSCENDENTAL,TYPE); 

( P1 ) TRANSCENDENTAL 

(C2) PUT(%PI,TRANSCENDENTAL,TYPE)$ 

(C3) PUT(%I, ALGEBRAIC, TYPE )i 

(C4) TYPEOF(X) := BLOCK([Q], IF NUMBERP(X) THEN RETURN(ALGEBRAIC), 

IF NOT ATOH(X) THEN RETURN(HAPLIST(TYPEOF, X)). 
Q : GET(X, TYPE). 
IF Q=FALSE THEN ERROR("NOT NUHERIC") ELSE Q)t 

(C5) TYPEOF(2*%E+X*%PI); 

NOT NUHERIC 

QUIT 

(C6) TYPEOF(2*%E+%PI); 

(D6) [[ALGEBRAIC, TRANSCENDENTAL], TRANSCENDENTAL] 



REMfa i) removes the property indicated by / from the atom a. 

NUMERVALfvarl, expl, var2, exp2, ...) declares vari to have a numerical value of 
expl which is evaluated and substituted for the variable in any expressions 
in which the variable occurs if the NUMER flag is TRUE (see the EV function, 
sec. 6.1.1). 
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9 Pattern Matching and Related Functions 

[9.1] Type Testing Functions 



ATObA(exp) is TRUE if exp is atomic (i.e. a number or name) else FALSE. Thus 
AT0M(5) is TRUE while AT0M(A[1]) and ATOM(SIIVKX)) are FALSE. (Assuming 
A[l] and X are unbound.) 



SUBVARPfexpJ is TRUE if exp is a subscripted variable, for example A[IJ 



CONSTANTPfexp; is TRUE if exp is a constant (i.e. composed of numbers and 7.PI, 
7.E, %\ or any variables bound to a constant or DECLAREd constant (see 8.1.1) 
else FALSE. Any function whose arguments are constant is also considered to 
be a constant. 



NONSCALARPfexpf is TRUE if exp is a non-scalar, i.e. it contains atoms declared 
as non-scalars (see 8.1), lists, or matrices. 



INTEGERPfexp; is TRUE if exp is an integer else FALSE 



EVENPfexp; is TRUE if exp is an even integer. FALSE is returned in all other 
cases. 



ODDPfexp; is TRUE if exp is an odd integer. FALSE is returned in all other cases. 
FLOATNUMPfexp,) is TRUE if exp is a floating point number else FALSE 
BFLOATPfexp; is TRUE is exp is a bigfloat number else FALSE 
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NUMBERPfep; is TRUE if exp is an integer, a rational number, a floating point 
number or a bigfloat else FALSE 



se 



RAT FALSE reXP; ^ TRUE ^ ^ IS a rall0na, nUmber <lnC,UdeS inle * ers) el 

LISTPfexp^ is TRUE if exp is a list else FALSE 

MATRIXPfexp; is TRUE if exp is a matrix else FALSE 

RATPfexp; is TRUE if exp is in CRE or extended CRE form else FALSE 

FREEOFW, x2 ., exp) yields TRUE if the xl do not occur in exp and FALSE 
otherw^ The x/ are atoms or they may be subscripted names, functions 
(e.g. SIN(X) ), or operators enclosed in w s. They may also be lists of these 

— _,—=-.—. 

(CI) FREE0F(Y,SIN(X+2*Y)); 

(01) FALSE 

(C2) FREEOF(COS(Y),"*\SIN(Y)+COS(X)); 

(° 2 > TRUE 

[9.2] General Pattern Matching Functions 

The pattern matching functions permit the user to test expressions for 
combinations of syntactic and semantic patterns and to automatically have 
variables set to parts of expressions which fit the patterns. This enables one to 
transform an expression as well as to see if it fits a pattern. 

It is also possible to add simplification rules which apply to user or system 
defined functions or operators. In order to choose the particular rule which 
applies, a pattern match must usually be performed on the operands of the 
expression which is to be simplified. 
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MATCHDECLAREfpafternvar, predicate, ...) associates a predicate with a pattern 
variable so that the variable will only match expressions for which the 
predicate is not FALSE. (The matching is accomplished by one of the 
functions described below). For example after 

MATCHDECLARE(Q,FREEOF(X,%E)) is executed, Q will match any expression 
not containing X or 7.E. If the match succeeds then the variable is set to the 
matched expression. The predicate (in this case FREEOF) is written without 
the last argument which should be the one against which the pattern variable 
is to be tested. Note that the patternvar and the arguments to the predicate 
are evaluated at the time the match is performed. 

The odd numbered argument may also be a list of pattern variables all of 
which are to have the associated predicate. Any even number of arguments 
may be given. 

For pattern matching, predicates refer to functions which are either 
FALSE or not FALSE (any non FALSE value acts like TRUE). 

MATCHDECLARE(var,TRUE) will permit var to match any expression. 

PRINTPR0PS([v;,v2,...],MATCHDECLARE) (see 8.1.1) will display the 
matchdeclare properties of the variables vl,v2,... 



TELLSIMPAFTERfpaftery^ replacement) defines a replacement for pattern which 
the MACSYMA simplifier uses after it applies the built-in simplification rules. 
The pattern may be anything but a single variable or a number. 



TELLSMP (pat tern, replacement) is similar to TELLSIMPAFTER but places new 
information before old so that it is applied before the built-in simplification 
rules. The pattern may not be a sum, product, single variable, or number. 
RULES is a list of names- having simplification rules added to them by 
DEFRULE, DEFMATCH, TELLSIMP, or TELLSIMPAFTER. 
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(CI) MATCHDECLARE([XX,A,B],TRUE); 



(Dl) 



DONE 



(C2) 
TELLSIMP(D[XX](A,B) f B(XX)*DIFF(A(XX),X)-A(XX)*DIFF(B(XX),XX)); 

RULE PLACED ON SUBVAR 

( D 2) [SUBVARRULE1, FALSE] 



SUBVARRULE1 is the name assigned to the TELLSIMP rule from (C34). 

(C3) D[Z](X,Y); 

(D3) Y(Z) X(Z) - X(Z) Y(Z) 



Another example of the use of TELLSIMP is shown in the following: 
(C4) (TO; 

(TO HAS BEEN GENERATED 

To override such default simplification, the user can use the following 
paradigm: 

(C5) BLOCM[SIMP],SIMP:FALSE,TELLSIMP(0*0,l)h 

RULE PLACED ON ** 

(05) [**RULE1, SIMPEXPT] 

(C6) (TO; 

(D6) ■ ' 1 

(C7) .REMRULE("**\"**RULE1 ,, ); 

(07) C SIMPEXPT ] 



DEFMATCHfprogname, pattern, parml, ..., parmn) creates a function of n+1 
arguments with the name progname which tests an expression to see if it can 
match a particular pattern. The pattern is some expression containing pattern 
variables and parameters. The parms are given explicitly as arguments to 
DEFMATCH while the pattern variables (if supplied) were given implicitly in a 
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previous MATCHDECLARE function. The first argument to the created 
function progname, is an expression to be matched against the "pattern 14 and 
the other n arguments are the actual variables occurring in the expression 
which are to take the place of dummy variables occurring in the "pattern" 
i hus the parms in the DEFMATCH are like the dummy arguments to the 
SUBROUTINE statement in FORTRAN. When the function is "called" the actual 
arguments are substituted For example: 

(Cl) NONZEROAN0FREEOF(X,E):= IF E#0 AND FREEOF(X.E) 
THEN TRUE ELSE FALSE! 

(iS(E#o and freeof(x.E)) is an equivalent function definition - see sec. 

8. 1 . 1 . 

(C2) MATCHDECLARE(A.NONZEROANDFREEOF(X),B.FREEOF(X))t 
(C3) DEFMATCH(LINEAR,A*X+B,X)t 

This has caused the function UNEAR(exp,vari) to be defined. It tests 
exp to see if it is of the form A*var/+B where A and B do not contain varl 
and A is not zero. DEFMATCHed functions return (if the match is successful) 
a list of equations whose left sides are the pattern variables and parms and 
whose right sides are the expressions which the pattern variables and 
parameters matched. The pattern variables, but not the parameters, are set 
to the matched expressions. If the match fails, the function returns FALSE 
Thus LINEAR(3*Z+(Y+1)*Z+Y**2,Z) would return [B=Y**2, A=Y+4, X=Z]. Any 
variables not declared as pattern variables in MATCHDECLARE or as 
parameters in DEFMATCH which occur in pattern will match only themselves 
mm^ ' f the third ar * ument *° the DEFMATCH in <C4) had been omitted, then 
LINEAR would only match expressions linear in X, not in any other variable. 

A pattern which contains no parameters or pattern variables returns 
TRUE if the match succeeds. 

(Cl) MATCHDECLARE([A,F],TRUE)i 

(C2) CONSTINTERVAL(L,H): S CONSTANTP(H-L)t 

<C3) MATCHDECLARE(B,CONSTINTERVAL(A))t 

(C4) MATCHDECLARE(X,ATOM)t 

<C5) BLOCM REMOVE* INTEGRATE. LINEAR). 
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DEFMATCH(CHECKLIHITS, 'INTEGRATE^, X,A»B), 
DECLARE ( INTEGRATE, LINEAR) )f 

(C6) 'INTEGRATE(SIN(T),T,X+XPI,X+2*XPI)I 

(C7) CHECKLIHITS(X); 

(07) [B = X ♦ 2 XPI, A = X ♦ XPI, X = T, 

F » SIN(T)] 

(C8) 'INTEGRATE(SIN(T),T,0,X)t 

(C9) CHECKLIMITS(X); 

(09) FALSE 



DEFR\JLE(rulename, pattern, replacement) defines and names a replacement rule 
for the given pattern. If the rule named rulename is applied to an expression 
(by one of the APPLY functions below), every subexpression matching the 
pattern will be replaced by the replacement All variables in the replacement 
which have been assigned values by the pattern match are assigned those 
values in the replacement which is then simplified. The rules themselves can 
be treated as functions which will transform an expression by one operation 
of the pattern match and replacement. If the pattern fails, the original 
expression is returned 



APPLY \(exp, rulel, ..., rulen) repeatedly applies the first rule to exp until it fails, 
then repeatedly applies the same rule to all subexpressions of exp, left-to- 
right, until the first rule has failed on all subexpressions. Call the result of 
transforming exp in this manner exp\ Then the second rule is applied in the 
same fashion starting at the top of exp\ When the final rule fails on the final 
subexpression, the application is finished. 



APPLY2(exp, rulel, ..., rulen) differs from APPLY1 in that if the first rule fails on 
a given subexpression, then the second rule is repeatedly applied, etc. Only 
if they all fail on a given subexpression is the whole set of rules repeatedly 
applied to the next subexpression. If one of the rules succeeds, then the 
same subexpression is reprocessed, starting with the first rule. 
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MAXAPPLYDEPTH[ 10000] is the maximum depth to which APPLY1 and 
APPLY2 will delve. 



APPLYBUexp, rulel, ..., rulen) is similar to APPLY1 but works from the "bottom 
up" instead of from the "top down". That is, it processes the smallest 
subexpression of exp, then the next smallest, etc. 

MAXAPPLYHEIGHT[ 10000] - is the maximum height to which APPLYB1 will 
reach before giving up. 



[9.3] Pattern Matching for Rational Expressions 



LETSIMPfexpJ will continually apply the substitution rules previously defined by 
the function LET (see below) until no further change is made to exp. 



LETtprod, repl, predname, argl, arg2, ..., argn) defines a substitution rule for 
LETSIMP such that prod gets replaced by repl. prod is a product of positive 
or negative powers of the following types of terms: 

(1) Atoms which LETSIMP will search for literally unless previous to 
calling LETSIMP the MATCHDECLARE function is used to associate a predicate 
with the atom. In this case LETSIMP will match the atom to any term of a 
product satisfying the predicate. 

(2) Kernels such as SIN(X), N!, F(X,Y), etc. As with atoms above LETSIMP 
will look for a literal match unless MATCHDECLARE is used to associate a 
predicate with the argument of the kernel. 

A term to a positive power will only match a term having at least that 
power in the expression being LETSIMPed. A term to a negative power on 
the other hand will only match a term with a power at least as negative. In 
the case of negative powers in "product" the switch LETRAT must be set to 
TRUE (see below). 

If a predicate is included in the LET function followed by a list of 
arguments, a tentative match (i.e. one that would be accepted if the predicate 
were omitted) will be accepted only if predname{argl\..,argri) evaluates to 
TRUE where arg? is the value matched to argl The argi may be the name of 
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any atom or the argument of any kernel appearing in prod, repl may be any 
rational expression, if any of the atoms or arguments from prod appear in 
repl the appropriate substitutions will be made. 

LETRAT[FALSE] when FALSE, LETSIMP will simplify the numerator and 
denominator of expr independently and return the result. Substitutions such 
as N!/N goes to (N-l)! will fail. To handle such situations LETRAT should be 
set to TRUE, then the numerator, denominator, and their quotient will be 
simplified in that order. 

These substitution functions allow you to work with several rule 
packages at once. Each rule package can contain any number of LETed rules 
and is refered to by a user supplied name. To insert a rule into the rule 
package name, do lEl{\prod,repl t pred,argl r ..\name). To apply the rules in 
rule package name, do LETSIMP(expr, name). The function 
LETSIMPC expr,namel,name2,...) is equivalent to doing LETSIMR expr t namel) 
followed by LETSIMP<7.,naroe2) etc. 

There is a default rule package name which is assumed when no other 
name is supplied to any of the functions. Whenever a LET includes a^ rule 
package name the default rule package is made to look like that rule package. 

REMLET (prod, name) deletes the substitution rule, prod — > repl, most recently 
defined by the LET function. If name is supplied the rule is deleted from the 
rule package name. REMLETO and REMLET(ALL,naroe> delete ail substitution 
rules from the default rule package. If name is supplied the rule package, 
name, is also deleted. 

If a substitution is to be changed using the same product, REMLET need not 
be called, just redefine the substitution using the same product (literally) with 
the LET function and the new replacement and/or predicate name. Should 
REMLET(product) now be called the original substitution rule will be revived. 

LETRULESfname; and LETRULESO display the rules in the default rule package and 
the rule package, name, respectively. Note that the function LETRULES( name) 
will set the default rule package to the rule package, name. 

(CI) MATCHDECLARE([A1,A2],TRUE)I 

(C2) 0NELESS(X,Y):=IS(EQUAL(X,Y-1))S 

(C3) LET(A1*A2!,A1!,0NELESS,A2,A1); 
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(03) Al A2! — > All WHERE 0NELESS(A2, Al) 

(C4) LETRAT:TRUEt 

(C5) LET(A1!/A1,(A1-1)!); 

Al! 
(D5) > (Al - 1)! 

Al 

(C6) LETSIHP(N*H!*(N-1)!/M); 

(D6) (M - 1)! N! 



The user should be aware that simplification rules for differential operators 
can be specified using MACSYMA's pattern-matching commands. 

Consider a function F(X). To inform MACSYMA that F depends on X, the 
user must type DEPENDS(F,X); (otherwise, DJFF(F,X) will return 0). We will 
assume that this has been done and that DERIVABBREV has been set to TRUE 
in the following example. 

Now suppose that the function F(X) satisfies some constraint, say that 
the cTAIembertian of f(x) is zero: 

D 2 f(x) « 0. 

In a curved space, this may take the form: 



(C4) -2*(DIFF(F,X)*X +2) 

*(L*(DIFF(F,Xr3)*X*2 

+(4*DIFF(F,X,2)+4*(DIFF(F,X) A 2))*X+8«DIFF(F f X)); 
3 2 2 

(04) - 2 (F X ♦ 2) ((F ) L X ♦ (4 F ♦ 4 (F ) ) X ♦ 8 F ) 
XX XXX X 



One can solve for the second-order term: 
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(C5) S0LVE(%,DIFF(F,X,2)); 
Solution 

3 2 2 

(F ) L X ♦ 4 (F ) X .♦ 8 F 
X X X 

(E5) F 

XX 4 X 

(D5) [E5] 



which can be restated as a simplification rule: 



(C6) LET(DIFF(F,X,2),RHS(E5)); 

(D6) (F --> RHS(E5)) 

Then a relatively complicated expression such as 

4 2 3 3 2 

(D10) ((F ) L X ♦ (8 F F L ♦ 8 (F ) L) X 
X XXX X 

2 
+ ((F ) (12 L ♦ 16) ♦ 16 F ) X ♦ 32 F ) 
X XX X 

2 2 
/(X ((F ) L X + 4 F X ♦ 4)) 
X X 

can be simplified using the LETSIMP command: 

(Cll) FACTOR(LETSIHP(%)); 

2 

(Dll) - (F ) L 

X 



1 70 MACSYMA 

1 Utility, Input-Output, and Display Functions 

[ 1 0. 1 ] Debugging Functions 



The functions In this section permit the user to examine his MACSYMA 
environment and to obtain debugging information. Further detail is given in section 
1 2.0. 



TRACECnamei, name2, ...) gives a trace printout whenever the functions 
mentioned are called. TRACEO prints a list of the functions currently under 
TRACE. 



UNTRACEfaame/, ...) removes tracing incurred by the TRACE function. UNTRACEO 
removes tracing from all functions. 



REMTRACEfl removes the tracing facilities from MACSYMA thus freeing up some 
storage. They will be reloaded when TRACE is used again. 



DECLAREf/Var/, var2, ..J BINDTEST) causes MACSYMA to give an error message 
whenever any of the vari occur unbound in a computation. 



BREbKfargl, ...) evaluates and prints its arguments then enters a MACSYMA break 
loop. 



Options and Variables 



%7. is the value of the last computation performed while in a (MACSYMA- 

BREAK). 

DEBUGMODE[FALSE] if TRUE causes MACSYMA to enter a MACSYMA break 
loop whenever a MACSYMA error occurs. If DEBUGMODE:ALL then the user may 
examine BACKTRACE for the list of functions currently entered. 
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REFCHECK[FALSE] if TRUE causes a message to be printed each time a 
bound variable is used for the first time in a computation. 

PREDERRC7[TRUE] - if TRUE causes a message to be printed whenever the 
predicate of an IF statement or an IS function fails to evaluate to either TRUE or 
FALSE. 

SETCHICKJTALSE] - if set to a list of variables (which can be subscripted) 
will cause a printout whenever the variables, or subscripted occurrences of them, 
are bound (with : or :: or function argument binding). The printout consists of the 
variable and the value it is bound to. SETCHECK may be set to ALL or TRUE 
thereby including all variables. 

SETCHECKBREAK[FALSE] - if set to TRUE will cause a (M ACSYM A-BREAK) 
to occur whenever the variables on the SETCHECK list are bound. 

BACKTRACE (when DEBUGM0DE:ALL has been done) has as value a list of at! 
functions currently entered, (see Chapter 19). 



10.2 Functions for DisnSavinff 



DISPFUN/f7, f2, ...) displays the definition of the user defined functions fl, f2, ... 
which may also be the names of array associated functions, subscripted 
functions, or functions with constant subscripts which are the same as those 
used when the functions were defined. DISPFUN(ALL) will display all user 
defined functions as given on the FUNCTIONS and ARRAYS lists except 
subscripted functions with constant subscripts. 



DISPRULEfru/ename,) will display a rule with the name rulename as was given by 
DEFRULE, TELLSIMP, or TELLSIMPAFTER or a pattern defined by 
DEFMATCH. For example, the first rule modifying SIN will be called 
SINRULE1. (see 9.2) 



DISPLAYfexpi, exp2, ...) displays equations whose left side is expi unevaluated, 
and whose right side is the value of the expression centered on the line. 
This function is useful in blocks and FOR statements in order to have 
intermediate results displayed. The arguments to DISPLAY are usually atoms, 
subscripted variables, or function calls, (see the DISP function below.) 
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(CI) DISPLAY(B[1,2]); 

2 
B = X - X 

1. 2 

(01) DONE 

LDISPLAY (expl,exp2,...) is like DISPLAY but also generates intermediate labels. 



DISP (expl,exp2, ...) is like DISPLAY but only the value of the arguments are 
displayed rather than equations. This is useful for complicated arguments 
which don't have names or where only the value of the argument is of 
interest and not the name. 



LQ\SP(expl,exp2,...) is like DISP but also generates intermediate labels. 



PRINT (expl, exp2, ...) evaluates and displays its arguments one after the other 
"on a line" starting at the leftmost position. If expi is unbound or is preceded 
by a single quote or is enclosed in M s then it is printed literally. For example, 
PRINT* "THE VALUE OF X IS ",X). The value returned by PRINT is the value of 
its last argument. No intermediate lines are generated 



DISPTERMSfexp,) displays its argument in parts one below the other. That is, 
each term in a sum or factor in a product is displayed separately. This is 
useful if exp is too large to be otherwise displayed. For example if PI, P2, ... 
are very large expressions then the display program may run out of storage 
space in trying to display P1+P2+... all at once. However, 
DISPTERMS(P1+P2+...) will display PI, then below it P2, etc. When not using 
DISPTERMS, if an exponential expression is too wide to be displayed as A**B 
it will appear as EXPT(A.B) (or as NCEXPT(A,B) in the case of A^B). 



REVEAL(exp,depth) will display exp to the specified integer depth with the length 
of each part indicated. Sums will be displayed as SUM(n) and products as 
PRODUCT(n) where n is the number of subparts of the sum or product. 
Exponentials will be displayed as EXP. 
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(Cl) INTEGRATE* 1/(X A 3+2),X)« 

(C2) REVEAL(%,2); 

(D2) PR0DUCT(3) + PR0DUCT(3) ♦ PR00UCT(3) 

(C3) REVEAL(D1,3); 

EXPT LOG EXPT LOG 

(D3) ♦ EXPT EXPT ATAN + 

6 3 



PLAYBACK (arg) "plays back" input and output lines. If arg=n (a number) the last 
n expressions (Ci, Di, and Ei count as 1 each) are H played-back" ; while if arg 
is omitted, all lines are. If argMNPUT then only input lines are played back. If 
arg=[m t r\] then all lines with numbers from m to n inclusive are played-back. 
If m=n then [m] is sufficient for arg. Arg=SL0W places PLAYBACK in a slow- 
mode similar to DEMO's (as opposed to the "fast" BATCH). This is useful in 
conjunction with SAVE or STRINGOUT (see below) when creating a 
secondary-storage file in order to pick out useful expressions. If arg^TIME 
then the computation times are displayed as well as the expressions. 
ar^=NOSTRING displays all input lines when playing back rather than 
STRINGing them. If arg^GRIND then the display will be in a more readable 
format. One may include any number of options as in 
PLAYBACK([5,10],20,TIME,SL0W). 



STRINGfexp; converts exp to MACSYMA's linear notation (similar to FORTRAN'S) 
just as if it had been typed in and puts exp into the buffer for possible 
editing (in which case exp is usually Ci) (see sec. 14.2). The STRING'ed 
expression should not be used in a computatioa 

STRINGOUT^args; will output an expression to a file in a linear format. 
STRINGOUT([filespec],...,FUNCT!ONS,...) puts all the user's function definitions 
in the specified file, (see 10.4) 

GRIND[FALSE] if TRUE will cause the STRING, STRINGOUT, and PLAYBACK 
commands to use "grind" mode instead of "string" mode. For PLAYBACK, 
"grind" mode can also be turned on (for processing input lines) by specifying 
GRIND as an option. 
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GR\N0(arg) prints out arg in a more readable format than the STRING command. It 
returns a D-line as value. 



FORTRANfexp; converts exp into a FORTRAN linear expression in legal FORTRAN 
with 6 spaces inserted at the beginning of each line,continuation lines,and ** 
rather than " for exponentiation. When the option FORTSPACES[FALSE] is 
TRUE, the FORTRAN command fills out to 80 columns using spaces. 



FORTMX(name,matrix) converts a MACSYMA matrix into a sequence of FORTRAN 
assignment statements of the form 
name{ i,j)= <the ij matrix element> 



DESCRIBE(7uncf/on; prints out the portion of the MACSYMA manual describing the 
function. 



EXkhAPLE(function) does a DEMO of relevant examples involving function. 
1 0.3 Functions for Freeing Storage 



REMOVE(args) will remove some or all of the properties associated with variables 
or functions, (see 8.1) 



REMFUNCTIONfYJ, f2, ...) removes the user defined functions fl,f2,... from 
MACSYMA. If there is only one argument of ALL then all functions are 
removed 



REMVALUEfaame/, name2, ...) removes the values of user variables (which can be 
subscripted) from the system. If name is ALL then the values of all user 
variables are removed. Values are those items given names by the user as 
opposed to those which are automatically labeled by MACSYMA as Ci f Di, or 

Ei. 
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REMARRAYfoamei, name2, ...) removes arrays and array associated functions and 
frees the storage occupied. If name is ALL then ail arrays are removed, it 
may be necessary to use this function if it is desired to redefine the values in 
a hashed array. 



REMR\JLE( function, rulename) will remove a rule with the name rulename from the 
function which was placed there by DEFRULE, DEFMATCH, TELLSIMP, or 
TELLSIMPAFTER. If rule-name is ALL, then all rules will be removed, (see 
example in 9.2) 



KllUargl, arg2, ...) eliminates its arguments from the MACSYMA system. If argi is 
a variable (including a single array element), function, or array, the designated 
item with all of its properties is removed from core. If ar£/=LABELS then all 
input, intermediate, and output lines to date (but not other named items) are 
eliminated. If arg/=CLABELS then only input lines will be eliminated; if 
argi=El ABELS then only intermediate E-Hnes will be eliminated; if 
arg/=DLABELS only the output lines will be eliminated. If argi is the name of 
any of the other information lists (the elements of the MACSYMA variable 
INFOLISTS), then every item in that class (and its properties) is KILLed and if 
arg7=ALL then every item on every information list previously defined as well 
as LABELS is KILLed If argi=a number (say n), then the last n lines (i.e. the 
lines with the last n line numbers) are deleted. If argi is of the form [m,n] 
then all lines with numbers between m and n inclusive are killed. Note that 
KILL(VALUES) or KILL(variable) will not freeup the storage occupied unless 
the labels which are pointing to the same expressions are also KILLed. Thus 
if a large expression was assigned to X on line C7 one should do KILL(D7) as 
well as KILL(X) to release the storage occupied. 

KILL(ALLBUT(name/,...,name*)) will do a KILL(ALL) except it will not KILL 
the names specified. 

KILL removes all properties from the given argument; thus KILL(VALUES) 
will kill aH properties associated with every item on the VALUES list. KILL 
always returns the value "DONE" even if the named item doesn't exist (see 
8.1). 

The "REMOVE" functions (REMVALUE.REMFUNCTION, 

REMARRAY,REMRULE) remove a specific property. These functions return a 
list of names or FALSE (if the specific argument doesn't exist). 
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MACSYMA options may not be Killed The user may do RESETO (see 
10.6) to reset all options to their default values. 

The error message "NO CORE - FASLOAD" results when either too man^ 
FASL files have been loaded in or when allocation level has gotten too high. 
Note that once this occurs, KILLing expressions will not help. In either of 
these cases, no amount of killing will cause the size of these spaces to 
decrease. Killing expressions only causes some spaces to get emptied out 
but not made smaller. 



1 0.4 Functions Which Reference Disk Files 



LOADFILE<7n/, fn2, DSK, directory) loads a file as designated by its arguments. 
This function may be used to bring back quantities that were stored from a 
prior MACSYMA session by use of the SAVE or STORE functions. If DSK and 
directory are omitted then the last directory seen (initially the same as the 
user's login name or USERS if the user has no file directory) will be used. If 
DSK and directory are omitted, fn2 may also be omitted if fnl > is to be 
loaded in (where > follows the conventions of ITS's file system). Fnl fn2 
must be a file of LISP functions and expressions, not of MACSYMA command 
lines, in which case BATCH or DEMO is to be used. (See Chapter 14). 

Q£LF\LE(fi/e-specification) will delete the file given by the file-specification. 



BATCH(fife-specification) reads in and evaluates MACSYMA command lines from a 
file, (see Chapter 14). 



DEMO( file-specification) same as BATCH but pauses after each command line and 
continues when a space is typed, (see Chapter 14). 



BATCOW 'argument) continues BATCHing in a file which was interrupted (see 
14.4). 



MACSYMA 10.4 Functions Which Reference Disk Files 177 

WRITEFILEfDS/C, directory} opens a file for writing. 

APPENDFlLEftf/enameJ, filename^ DSK, directory) is like 

WRITEFILE(DSK,o7rectory) but appends to the file whose name is specified by 
the first two arguments. A subsequent CLOSEFILE will delete the original file 
and rename the appended file. 

CLOSEFILE<7/7enamei, filename 2) closes a file opened by WRITEFILE and gives it 
the name filename 1 fHename2. Thus to save a file consisting of the display of 
all input and output during some part of a session with MACSYMA the user 
issues a WRITEFILE, transacts with MACSYMA, then issues a CLOSEFILE. The 
user can also issue the PLAYBACK function after a WRITEFILE to save the 
display of previous transactions. (Note that what is saved this way is a copy 
of the display of expressions not the expressions themselves). To save the 
actual expression in internal form the SAVE function may be used. The 
expression can then be brought back into MACSYMA via the LOADFILE 
function. To save the expression in a linear form which may then be 
BATCHed in later, the STRINGOUT function is used, (see below) 

STRMGOUKfife-specification, AI, A2, ...) outputs to a file given by file- 
specification ([filename l,fi!ename2,DSK, directory]) the values given by 
Al,A2 y . in a MACSYMA readable format. The file-specification may be 
omitted, in which case the default values will be used (see 15.2 - C) 
The Ai are usually C labels or may be INPUT meaning the value of all C labels. 
Another option is to make Ai FUNCTIONS which will cause all of the user's 
function definitions to be strungout (i.e. all those retrieved by DISPFUN(ALD). 
Ai may also be a list [m,n] which means to stringout all labels in the range m 
through n inclusive. This function may be used to create a file of FORTRAN 
statements by doing some simple editing on the strungout expressions. The 
FORTRAN[FALSE] should be set to TRUE, however, to cause exponentiation 
to be strung as ** rather than as ", as well as to effect other FORTRAN-like 
changes. Alternatively, the function FORTRAN can be used (see 10.2) 

StKVE(args) saves quantities described by its arguments on disk and keeps them in 
core also, (see 15.3). 
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STORE(args) same as SAVE but doesn't retain quantities in core, (see 1 5.3). 



rAC'CA\fr/4fff(>l itf similar tn CAV/C" ki it r\rfu4iu*A€t a FA CI ISIa in uukirh tKtA ekarino nf 

rn«Jjn»U|Hlgii/ l^ 0iiiiilai *w «;nfu hfui |*i wwvivw* « ■ ns/b in** •■• vWiiiVit »■ .w wnm nig w. 

subexpressions which are shared in core is preserved in the file created. 
Hence, expressions which have common subexpressions will consume less 
space when loaded back from a file created by FASSAVE rather than by 
SAVE. 



UNSTOREfnaroeJ, ...) brings the named expressions into core that were stored 
away by use of the STORE function in the current MACSYMA. (see 
1 5.3). 



RESTORE* file-specification) reinitializes all quantities filed away by a use of the 
SAVE or STORE functions, in a prior MACSYMA session, from the file given by 
fife-specification without bringing them into core, (see 15.4). 



REMFILE(9 removes files created by the secondary storage scheme in the 
MACSYMA under use (see 15.2). REMFILE(ALL) does what REMFILEO 
does and in addition deletes any files which have been created by the SAVE 
or STORE functions but which have not been assigned names by the user. 



[10.5] Ordering Functions 



Aside from declaring a variable to be constant or using options like 
POWERDISP (see below), the only other way in which a user can alter the 
ordering of parts of an expression is to set up special aliases for variables which 
cause them to be alphabetically less than or greater than any other variables. 
Functions which do this are described below. This technique requires care 
because although the names have been aliased, they display with their original 
name. Aside from the input/output phase the two names represent two different 
symbols and thus expressions which contain both the original name and the alias 
will not be simplified as the user desires. This is shown in the examples below. 
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ORDERGREATfl/J, ..., Vn) sets up aliases for the variables VI, ..., Vn such that 
VI > V2> ... > Vn > any other variable not mentioned as an argument. 



ORDERLESSft//, ..., Vn) sets up aliases for the variables VI, ..., Vn such that 
VI < V2< ... < Vn < any other variable not mentioned as an argument. 



Thus the complete ordering scale is: 

numerical constants < declared constants < 

< first argument to ORDERLESS < ... < last argument to ORDERLESS < 

< variables which begin with A < ... < variables which begin with Z < 

< last argument to ORDERGREAT < ... < first argument to ORDERGREAT. 

ORDERGREATPfexpi,exp2; returns TRUE if exp2 precedes expl in the ordering 
induced by the variabie ordering described above. 



0RDERLESSPfexpi,exp2; returns TRUE if expl precedes exp2 in the ordering 
induced by the variable ordering described above. 



UNORDERS removes the aliases created by the last use of the above ordering 
commands. ORDERGREAT and ORDERLESS may not be used more than one 
time each without calling UNORDER. 



(Cl) A**2+B*X; 






2 


(Dl) 


B X ♦ A 


(C2) ORDERGREAT(A); 




(02) 


DONE 


(C3) A**2+B*X; 






2 


(D3) 


A ♦ B X 


(C4) %-Dl; 
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2 2 

(D4) A - A 



(Cb) UNORDERO; 

(05) [A] 



SORT (list,optional-predicate) sorts the list using a suitable optional-predicate of 
two arguments (such as H <" or ORDERLESSP). If the optional-predicate is not 
given, then MACSYM A's built-in ordering predicate is used 



10.6 Miscellaneous Functions 



T\ME(Dil, Di2, ...) gives a list of the times in milliseconds taken to compute the Di. 



LOGOUTS causes the user to be logged out and all jobs deleted. This is useful 
when it is desired to BATCH in a file and have the terminal logged out 
automatically when the computations are finished. (Equivalent to ^Z and 
:L0G0UT) 



QUITO kills the current MACSYMA but doesn't affect the user's other jobs. 
(Equivalent to *2 and :KILL). 



READtstringl, ...) prints its arguments, then reads in and evaluates one expression. 
For example: A:READCENTER THE NUMBER OF VALUES"). 



REAQONLY(stringl,..,) prints its arguments, then reads in an expression (which in 
contrast to READ is not evaluated). 



DEFINEWx/, ...;, body) is equivalent to f(xl,...):="body but when used inside 
functions it happens at execution time rather than at the time of definition of 
the function which contains it. (see 3.2) 
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LOCALfW, v2, ...) causes the variables vl,v2,... to be local with respect to all the 
properties in the statement in which this function is used (see 2.12). LOCAL 
may only be used in BLOCKs, in the body of function definitions or LAMBDA 
expressions, or in the EV function and only one occurrence is permitted in 
each. 



ERROR(argl, arg2, ...) will evaluate and print its arguments and then will cause an 
error return to top level MACSYMA or to the nearest enclosing ERRCATCH. 
This is useful for breaking out of nested functions if an error condition is 
detected, or wherever one can't type control-G. 

ERRORFUN[FALSE] - if set to the name of a function of no arguments will 
cause that function to be executed whenever an error occurs. This is useful 
in BATCH files where the user may want his MACSYMA killed or his terminal 
logged out if an error occurs. In these cases ERRORFUN would be set to QUIT 
or LOGOUT. 



ERRCATCH (expi, exp2, ...) evaluates its arguments one by one and returns a list 
of the value of the last one if no error occurs. If an error occurs in the 
evaluation of any arguments, ERRCATCH "catches" the error and immediately 
returns [] (the empty list). This function is useful in BATCH files where one 
suspects an error might occur which would otherwise have terminated the 
BATCH if the error weren't caught. 



CATCHfexp/,...,expn>> evaluates its arguments one by one; if the. structure of the 
expi leads to the evaluation of an expression of the form THROW(arg), then 
the value of the CATCH is the value of THROW(arg). This M non-local return" 
thus goes through any depth of nesting to the nearest enclosing CATCH. 
There must be a CATCH corresponding to a THROW, else an error is 
generated. If the evaluation of the expi does not lead to the evaluation of 
any THROW then the value of the CATCH is the value of expn 



(CI) G(L):=CATCH(MAP(LAMBDA([X], 

IF X<0 THEN THROW(X) ELSE F(X)),L))t 

(C2) G<[1,2,3,7]); 

(02) [F(l), F(2), F(3), F(7)] 

(C3) G([l,2,-3,7]); 

(03) - 3 
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The function G returns a list of F of each element of L if L consists only 
of non-negative numbers; otherwise, G "catches" the first negative element of 
L and "throws" it up. 



THROWYexp; evaluates exp and throws the value back to the most recent CATCH. 
THROW is used with CATCH as a structured nonlocal exit mechanism. 



BREAK(arg7, ...) will evaluate and print its arguments and will then cause a 
( MACSYM A-BREAK) at which point the user can examine and change his 
environment. Upon typing EXIT; the computation resumes, (see Chapter 
19) 



RESETS causes all MACSYMA options to be set to their default values. 



XTH(i) is the /th previous computation. That is, if the next expression to be 
computed is D(j) this is D<j-/). This is useful in BATCH files or for referring 
to a group of D expressions. For example, if SUM is initialized to then FOR 
1:1 THRU 10 DO SUM:SUM+%TH(I) will set SUM to the sum of the last ten D 
expressions. 



CQHCKT(argl, arg2, ...) evaluates its arguments and returns the concatenation of 
their values resulting in a name or a quoted string (see 2.2 and 2.3) the type 
being given by that of the first argument Thus if X is bound to 1 and D is 
unbound then CONCAT(X,2)="12" and C0NCAT(D,X+1HD2 



GETCHARfe, i) returns the Ah character of the quoted string or atomic name a. 
This function is useful in manipulating the LABELS list 



STATUS (arg) will return miscellaneous status information about the user's 
MACSYMA depending upon the arg given. Permissible arguments and results 
are as follows: 

TIME - the time used so far in the computation. 
DAY - the day of the week. 
DATE - a list of the year, month, and day. 
DAYTIME - a list of the hour, minute, and second. 
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RUNTIME - accumulated cpu time times the atom "MSEC". 

REALTIME -the real time (in sec) elapsed since the user started up his 
MACSYMA. 

WRITEFILE - a list of the device and username for the current writefile 
or an empty list if no WRITEFILE has been done. 

LOADFILE - a list of the first file name, second file name, device, and 
username for the current BATCH, DEMO, or LOADFILE function. 

FILE - a list of the current first fife name and second file name. 

UNIT - a list of the current device and username. 



ALARMCLOCKfer^/, arg2, arg3) will execute the function of no arguments whose 
name is arg3 when the time specified by argl and arg2 elapses. If argl is 
the atom "TIME" then arg3 will be executed after arg2 seconds of real-time 
has elapsed while if argl is the atom "RUNTIME" then arg3 will be executed 
after arg2 milliseconds of cpu time. If arg2 is negative then the argl timer is 
shut off. 



LbBE\S(char) takes a char C,D,or E as arg and generates a list of all C-labels,D- 
iabeis, or E-iabeis, respectively. (If you've generated many E-fabels via 
SOLVE, then FIRST(REST(LABELS(C))); reminds you what the last C-label was.) 



ALlASfaewname/, oldnamel, newname2, oldname2, ...) provides an alternate name 
for a (user or system) function,variable,array,etc. Any even number of 
arguments may be used. 



[10.7] Options and Variables for I/O, Status, and Display 



GRIND[FALSE] if TRUE will cause the STRING, STRINGOUT, and PLAYBACK 
commands to use "grind" mode instead of "string" mode. For PLAYBACK, "grind" 
mode can also be turned on (for processing input lines) by specifying GRIND as an 
option. 

SHOWTIME[FALSE] - if TRUE causes MACSYMA to print the cpu time taken 
by each computation. This figure does not include I/O time except in the case of 
the time given at the end of running a batch file. By setting SHOWTIME:ALL, in 
addition to the cpu time MACSYMA now also prints out (when not zero) the 
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amount of time spent in garbage collection (gc) in the course of a computation. 
This time is of course included in the time printed out as "time=" . 

(It should be noted that cinro tka "tim*-" f ;«■>*» nnUi i^l^.A «.~_~..t~t:.._ t: 

and not any intermediate display time, and since it is difficult to ascribe 
"responsibility" for gc's, the gctime printed will include all gctime incurred in the 
course of the computation and hence may in rare cases even be larger than 
"time="). 

LASTTIME - the time to compute the last expression in milliseconds 
presented as a list. of "time" and "gctime" . 

OPTIONSET[FALSE] - if TRUE, MACSYMA will print out a message whenever 
a MACSYMA option is reset. This is useful if the user is doubtful of the spelling 
of some option and wants to make sure that the variable he assigned a value to 
was truly an option variable. 

NOLABELS[FALSE] - if TRUE then no labels will be bound except for E lines 
generated by the solve functions (sect 6.3). This is most useful in the "BATCH" 
mode where it eliminates the need to do KILL(LABELS) in order to free up 
storage. 

BFTRUNC[TRUE] causes trailing zeroes in non-zero bigfloat numbers not to 
be displayed. Thus, if BFTRUNC:FALSE, BFL0ATO); displays as 
1.000000000000000BO. Otherwise, this is displayed as 1.0B0. 

EXPTOISPFLAG[TRUE] - if TRUE, MACSYMA displays expressions with 
negative exponents using quotients e.g., X**(-l) as 1/X. 

%EDISPFLAG[FALSE] - if TRUE, MACSYMA displays %£ to a negative 
exponent as a quotient, i.e. %E*-X as 1/%E A X. 

SQRTDISPFLAG[TRUE] - if FALSE causes SQRT to display with exponent 1/2. 

PFEFORMAT[FALSE] - if TRUE will cause rational numbers to display in a 
linear form and denominators which are integers to display as rational number 

multipliers. 

DISPFLAG[TRUE] - if set to FALSE within a BLOCK (see 2.12) will inhibit the 
display of output generated by the solve functions (see 6.3) called from within the 
BLOCK. Termination of the BLOCK with a dollar sign, 3, sets DISPFLAG to FALSE. 
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LOADPRINT[TRUE] - governs the printing of messages accompanying loading 
of files. The following options are available: TRUE means always print the 
message; 'LOADFILE means print only when the LOADFILE command is used; 
'AUTOLOAD means print only when a file is automatically loaded in (e.g. the 
integration file SIN FASL); FALSE means never print the loading message. 

NOUNDISP[FALSE] - if TRUE will cause NOUNs to display with a single quote. 
This switch is always TRUE when displaying function definitions. 

POWERDISP[FALSE] - if TRUE will cause sums to be displayed with their 
terms in the reverse order. Thus polynomials would display as truncated power 
series, i.e., with the lowest power first. 

BOTHCASES[FALSE] - if TRUE will cause MACSYMA to retain lower case 
text as well as upper case. Note, however, that the names of any MACSYMA 
special variables or functions must be typed in upper case. 

STARDISPfFALSE] - if TRUE will cause multiplication to be displayed 
explicitly with an * between operands. 

DSKGCfFALSE] - if TRUE will cause user defined values, functions, arrays, 
and line labelled expressions to be automatically stored on disk whenever the 
system determines that the available in-core space is getting low (see also 
15.2). 

LABELS - a list of C, D, and E lines which are bound. 

INCHARfC] - the alphabetic prefix of the names of expressions typed by the 
user. 

LINECHAR[E] - the alphabetic prefix of the names of intermediate displayed 
expressions. 

0UTCHAR[D] - the alphabetic prefix of the names of outputted expressions. 

LINENUM - the line number of the last expression. 

CURS0R[_] is the prompt symbol of the MACSYMA editor, DEMO function, 
PLAYBACK(SLOW) mode, and (MACSYMA-BREAK). (see chapters 13 and 
19). 

GENINDEXfl] -the alphabetic prefix of the index of summation for generated 
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sums. (The values of GENINDEX and of the above four variables may be any 
number of characters though the default is a single character.) 



* r*r— r « ^*T 



iDAstiiuj - me Dase Tor inputting numoers. 

BASE[10] - the base for display of numbers. 

LINEL - the length of the printed line on the terminal. Also used for plotting 
(see Chapters 17 and 18). 

PLOTHEIGHT - the height of the area used for plotting (see Chapters 
17 and 18). 

VERSION[267] - is the version number of MACSYMA. This could be useful if 
the user wants to label his output. 

INFOLISTS is the list of all the information lists which are in MACSYMA: 

[LABELS,VALUES,FUNCTIONS,ARRAYS,MYOPTIONS l PROPS l ALIASES,RULE$, 

GRADEFS,DEPENDENCIES] 



Initially, all these information lists are empty. As the user proceeds with his 
computation, he may examine these lists when necessary. 
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[10.8] Functions for Translation and Compilation 



M0DEDECLARE(y/, model, y2, mode2, ...) is used to declare the modes of 
variables and functions for subsequent translation or compilation of functions. 
Its arguments are pairs consisting of a variable yi, and a mode which is one of 
BOOLEAN, INTEGER, NUMBER, RATIONAL, FLOAT, POLY (for polynomial), or 
CRE (for expression in CRE form). Each yi may also be a list of variables all 
of which are declared to have modeL 

If yi is an array, and if every element of the array which is referenced in the 
function has a value then ARRAY(y/ f COMPLETE, dl, d2, ...) rather than 
ARRAY(y/, dl, d2, ...) should be used when first declaring the bounds of the 
array. If all the elements of the array are of mode INTEGER (FLOAT), use 
INTEGER (FLOAT) instead of COMPLETE. Also if every element of the array is 
of the same mode, say m, then MODEDECLARE(COMPLETEARRAY(y/),ro)) should 
be used for efficient translation. Also numeric code using arrays can be made 
to run faster by declaring the expected size of the array, as in: 

MODEDECLARE(COMPLETEARRAY( A[ i 0,1 j),FL0AT) 
for a floating point number array which is 10 x 10. 

Additionally one may declare the mode of the result of a function by 
using FUNCTIONS 1,F2,...) as an argument; here Fl,F2 r .. are the names of 
functions. For example the expression, 

M0DEDECLARE([FUNCTI0N(Fl,F2,...),X],P0LY,Q,C0MPLETEARRAY(Q),FLOAT) 

declares that X and the value returned by F1,F2,... are polynomials and that Q 
is an array of floating point numbers. MODEDECLARE is used either 
immediately inside of a function definition (see below) or at top-level for 
global variables. 



OPTIMlZEfexp; returns an expression that produces the same value and side 
effects as exp but does so more efficiently by avoiding the recomputation of 
common subexpressions. OPTIMIZE also has the side effect of "collapsing" its 
argument so that all common subexpressions are shared. 
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(Cl) DIFF(X,X.2); 



* i ▼ a t*a t ♦ x y + x 

4 X XE 2 XE 4 X XE 2 XE 

(01) + + 

Y ♦ X Y ♦ X 2 3 

(Y ♦ X) (Y ♦ X) 



(C2) OPTIHIZE(X); 

2 Y ♦ T2 

(02) BL0CK([T1, 12. T3, T4], Tl : Y + X, 12 : X . T3 : XE 

* 4 X T3 2 T3 

T4: --, 4 12 T4 T3 ♦ 2 T4 T3 ♦ ) 

" 2 3 

TI Tl 



TRANSLATED, 12, .J translates the user defined functions fl,f2 t ... from the 
MACSYMA language to LISP (i.e. it makes them EXPRs). This results in a gain 
in speed when they are called. The functions should include a call to 
MODEDECLARE at the beginning when possible in order to produce more 
efficient code. For example: 

F(X1 ,X2, . . . ) :*BL0CK([vl,v2 f . . . J.H0DEDECLARE(vl,inodel,v2,inode2 f ...)....) 

where the XI, X2,... are the parameters to the function and the vl,v2,... are 
the local variables. The names of translated functions are added to the 
PROPS lists (see 8.1). Functions should not be translated unless they are 
fully debugged 

TRANSLATE(FUNCTIONS) or TRANSLATE(ALL) means translate all 
functions. 

TRANSLATEfFALSE] - If TRUE, causes automatic translation of a user's 
function to LISP. Note that translated functions may not run identically to the 
way they did before translation as certain incompatabilities may exist 
between the LISP and MACSYMA versions. Principally, the RAT function with 
more than one argument and the RATVARS function (see 6.5) should not be 
used if any variables are MODEDECLAREd CRE. 
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SAVEDEFfTRUE] - if TRUE will cause the MACSYMA version of a user 
function to remain when the function is TRANSLATEd. This permits the 
definition to be displayed by DISPFUN and allows the function to be edited. If 
SAVEDEF is FALSE, the names of translated functions are removed from the 
FUNCTIONS list. 

TRANSRUN[TRUE] - if FALSE will cause the interpreted version of all 
functions to be run (provided they are still around) rather than the translated 
version. 

TRANSBIND[TRUE] - if TRUE removes global declarations in the local 
context. This applies to variables which are formal parameters to functions. 

One can translate functions stored in a file by giving TRANSLATE an 
argument which is a file specification. This is a list of the form 
[fnl,fn2,DSK,dir] where fnl fn2 is the name of the file of MACSYMA functions, 
and dir is the name of a file directory. 

Such a file may contain declarations involving DECLARE,MODEDECLARE, or 
MATCHDECLARE in addition to the function definitions. The file should not 

USfi %. fiinCP "L i«J r\t\\ maintainor! uiKan IKa kf^n^\^ka.A CAa i*> i^^A^A 

The result returned by TRANSLATE is a list of the names of the functions 
TRANSLATEd. In the case of a file translation the corresponding element of 
the list is a list of the first and second new file names containing the LISP 
code resulting from the translation. This will be fnl LISP on the disk 
directory dir. The file of LISP code may be read into MACSYMA by using the 
LOADFILE function (see 10.4). 



C0MPF\lE([fiiespec] f fl,f2,...) will translate (if necessary) and write out MACSYMA 
function definitions and other expressions into a disk file which can be read 
into the compiler. The filespec (optional) specifies the file to be written. The 
default for users with a directory is CMPFIL > and the standard MACSYMA 
default file for other users. The file written contains declarations used by 
the compiler. When COMPGRIND[FALSE] is TRUE the function definitions are 
pretty-printed. The remaining arguments are atomic function names. 
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11 Tensor Manipulation 

MACSYMA implements symbolic tensor manipulation of two distinct types: 
explicit tensor manipulation and indicial tensor manipulation. 

Explicit tensor manipulation means that tensors are represented as arrays or 
matrices; tensor operations such as contraction or covariant differentiation are 
carried out by actually summing over repeated (dummy) indices — by explicitly 
performing operations on the appropriate tensor components stored in an array or 
matrix. 

Indicial tensor manipulation is implemented by representing tensors simply as 
functions of their covariant and contravariant indices; tensor operations such as 
contraction or covariant differentiation are represented by manipulating the 
indices themselves rather than the components which they refer to. 

These two approaches to the question of treating differential, algebraic and 
analytic processes in the context of Riemannian geometry have various advantages 
and disadvantages which reveal themselves only through the particular nature and 
difficulty of the user's problem. However, one should keep in mind the following 
characteristics of the two implementations: 

Explicit Tensor Manipulation (ETENSR) 

i) The standard representation of tensors and tensor operations 
explicitly in terms of their components makes ETENSR easy to use: 
specification of the metric and the computation of the induced tensors 
and invariants is straightforward. 

ii) Although all of MACSYMA's powerful simplification capacity is at 
hand, a complex metric with intricate functional and coordinate 
dependencies can easily lead to expressions whose size is excessive 
and whose structure is hidden. 

Indicial Tensor Manipulation (ITENSR) 

i) Because of the special way in which tensors and tensor 
operations are represented in terms of symbolic operations on their 
indices, expressions which in the explicit representation would be 
unmanageable can be greatly simplified by contraction and reduction to a 
"canonical" form (for symmetric tensors). In this way the structure of a 
iarge expression may be more transparent. 
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ii) On the other hand, because of the the special indicia! 
representation in ITENSR, in some cases the user must be careful about 
the specification of the metric, function definition, and the evaluation of 
differentiated "indexed" objects. 

These two tensor manipulation packages, ETENSR and ITENSR, are available to 
the MACSYMA user on the SHARE directory (see 12). To use the 
functions in these files, the user can load them in by doing 

LOADFILE(ETENSR,FASL,DSK,SHARE); — for explicit tensor manipulation. 

LOADFILE(ITENSR,FASL,DSK,SHARE); — for indicial tensor manipulation 

Both of these packages enable the user to specify a metric and compute the 
basic quantities of interest — Christoffel symbols, Riemann curvature tensor, 
curvature invariants — in the study of Riemannian manifolds. These routines were 
written primarily for research in gravitation theory? however, they may also be of 
some use in other areas of physics where Riemannian geometry is applied. 

11.1 Explicit Tensor Manipulation 



TSETUPfl automatically loads the ETENSR. package and presents several options 
which are self-explanatory. First the user chooses the kind of metric to be 
used — whether it will be one of the standard metrics already stored in some 
file, or a power-series approximation, or some new metric to be specified 
(perhaps only a slight modification of a metric already defined). After the 
metric has been specified, a number of simplification options are provided 
which govern the rational simplification and factoring of the tensor 
components to be computed The particular quantity to be computed can then 
be indicated; the user can say whether the results (some of which may be 
quite lengthy) are to be immediately displayed or not. 

Here is a sample protocol: 
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(C2) TSETUPO; 

DO YOU WANT » 

1 - TO CONSIOER A METRIC IN THE SPECIAL METRIC FILE? 

2 - TO APPROXIMATE A METRIC WITH A POWER SERIES? 

3 - TO ENTER A NEW METRIC? 
TYPE 1 OR 2 OR 3 

3; 

SPECIFY THE COORDINATES AS A LIST OF FOUR ELEMENTS 

[R,THETA,PHI,T]; 

DO YOU WANT 

1 - TO SPECIFY A DIAGONAL METRIC? 

2 - TO CHANGE A COMPONENT IN A PREVIOUSLY DEFINED 

METRIC? 

3 - TO SPECIFY A GENERAL (SYMMETRIC) METRIC? 
TYPE 1 2 OR 3 

l; 

ENTER DIAGONAL MATRIX 

CI. 1] 

-EXP(M); 

[2. 2] 

-R*2; 

[3, 3] 

-R*2*SIN(THETAr2; 

[4, 4] 

EXP(N); 

INDICATE THE KIND OF SIMPLIFICATION YOU WANT 

1 - RATIONAL SIMPLIFICATION ONLY 

2 - FACTORING AND RATIONAL SIMPLIFICATION 

3 - EXPANSION 
TYPE 1 2 OR 3 
2; 



At this point the user has the option of computing various quantities which 
are described below. 
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CHR\SJOF(arg) computes the Christoffel symbols of both kinds; the arg, 
determines which results are to be immediately displayed. The Christoffel 
symbols of the first kind are stored in the array LCS[I,J,K]. If the argument to 
CHRISTOF were LCS, all the non-zero values of LCS[I,J,K] would be displayed. 

The Christoffel symbols of the second kind (Mixed Christoffel Symbols) 
are given by the array MCS[I,J,K]; in the example below, the argument MCS 
was given resulting in the immediate display of all the non-zero mixed 
Christoffel symbols. 

(C.3) CHRISTOF(MCS); 

M 
R 
(E3) M CS 

I 

<E4) MCS 

1, 2, 2 R 

1 

(E5) MCS s - 

1, 3, 3 R 
N 
R 
(E6) MCS 

1, 4, 4 2 

- M 
(E7) MCS s - XE R 

2, 2, 1 

COS(THETA) 
(E8) MCS 

2, 3, 3 SIN(THETA) 
- M 2 
(E9) MCS = - %E R SIN (THETA) 

3, 3, 1 
(E10) MCS s - COS(THETA) SIN(THETA) 

3, 3, 2 

N - M 
XE N 
R 
(Ell) MCS 

4, 4, 1 2 

(Oil) DONE 
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MOTIONfc//s,) gives the geodesic equations of motion corresponding to a given 
metric. They are stored in the array EM[IJ If the argument dis is TRUE then 
these equations are displayed 



R\CC\COWdi$) This function first computes the contravariant components LR[I,J] of 
the Ricci tensor (LR is a mnemonic for "lower Ricci"). Then the mixed Ricci 
tensor is computed using the covariant metric tensor. If the value of the 
argument to RICCICOM is TRUE, then these mixed components, RICCI[I,J] (the 
index I is covariant (down) and the index J is contravariant (up) ), will be 
displayed directly. Otherwise, RICCICOM( FALSE) will simply compute the 
entries of the array RICCI[I,J] without presenting the results. 

(C13) RICCICON(TRUE); 

(E13) RICCI 

1, 1 

- H 2 

XE {{2 U ♦ (N ) - H N ) R - 4 N ) 
R R R R R R 

4 R 

- K N 
XE <<M - H ) R ♦ 2 XE - 2) 
R R 
(E14) RICCI 

2. 2 2 

2 R 



- M M 
XE ((H - N ) R ♦ 2 XE - 2) 
R R 
(E15) RICCI - 

3, 3 2 

2 R 
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(E16) RICCI 



4, 4 



- M 2 

%E ((2N +(N)-NN)R + 4N) 
R R R R R R 



4 R 
(016) DONE 



NTERMSRCIf? returns a list of pairs, whose second elements give the number of 
terms in the RICCI component specified by the first elements. In this way, it 
is possible to quickly find the non-zero expressions and attempt simplification. 

LRICCICOM(tf/s; computes the covariant components LR[I,J] of the Ricci tensor. If 
the argument di$ is TRUE, then the non-zero components are displayed. 

EINSTEiNfcfr's; computes the Einstein tensor once the Christoffel symbols and Ricci 
tensor have been obtained Again, if the argument evaluates to TRUE, then 
the non-zero values of the Einstein tensor G[I,J] will be displayed 
RATEINSTEIN:TRUE will perform rational simplification on these components; if 
FACRAT:TRUE then the components will also be factored 



NTERMSGfl gives the user a quick picture of the "size" of the Einstein tensor. It 
returns a list of pairs whose second elements give the number of terms in the 
components specified by the first elements. 

Of course a detailed examination of the structure of the Einstein components 
can be made using the powerful simplification, factoring and extraction functions 
available in MACSYMA (see 6.1.1,6.2.3). 



SCURVATUREfl returns the scalar curvature (obtained by contracting the Ricci 
tensor) of the Riemannian manifold with the given metric. 
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RIEMANNfaf/s; computes the Riemann curvature tensor from the given metric (the 
Christoffel symbols should be obtained first using CHRISTOF). If di$ is TRUE, 
the non-zero components R[I,J,K,L] will be displayed All the indicated indices 
are covanant As with the Einstein tensor, various switches set by the user 
control the simplification of the Riemann components. If RATRIEMAN:TRUE, 
then rational simplification will be done; if FACRAT:TRUE then each of the 
components will also be factored. 



(C27) RIEMANN(TRUE); 

H R 

R 
(E27) r 

1, 2, 1. 2 2 

2 

N R SIN (THETA) 
R 
(E28) R 

1. 3, 1, 3 2 

N * Z N 

- 2 XE N - XE (N ) ♦ N %E N 

M R R R 
(E29) R s 

.1. «. I. 4 4 

H - M 2 2 

< E3 °) R * - W - 1) XE R SIN (THETA) 

2. 3, 2. 3 

N - N 
XE N R 

R 

(E31) * 

2, 4. 2. 4 2 
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N - N 2 

%E N R SIM (THETA) 



(E32) R s ■ 

3, 4, 3, 4 2 

(D32) DONE 



RAISERIEMANN^/s; returns the contravariant components of the Riemann 
curvature tensor as array elements UR[I,J,K,L]. These are displayed if dis is 
TRUE. 



RINVARIANTfl forms the scalar invariant obtained by contracting 
R[I,J,K I L]*UR[I I J,K,L]. 



(C34) RINVARIANK ) ; 

-2M 2 2 4 

(034) %E ((4 (N ) + (4 (N ) - 4 M N ) N ♦ (N ) 

RR R RRRRR 

3 2 2 4 2 2 2 

- 2 M (N ) ♦ (M ) (N ) ) R ♦ (8 (N ) + 8 (H ) ) R 
R R R R R R 

2 M M 4 

+ 16 %E - 32 XE ♦ 16)/(4 R ) 



WEYL(dis) computes the Weyl conformal tensor. If the argument dis is TRUE, the 
non-zero components W[I,J,K,L] will be displayed to the user. Otherwise, 
these components will simply be computed and stored. If the switch 
RATWEYL is set to TRUE, then the components will be rationally simplified; if 
FACRAT is TRUE then the results will be factored as well. 
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QSCALbR(function) computes the d'Alembertian of the scalar function. 



(C41) DEPENDS(FIELD.R); 

<D41) [F!ELD{R}} 

(C42) DSCALAR( FIELD); 

(043) 
-M 
%E ((FIELD N - FIELD H ♦ 2 FIELD ) R ♦ 4 FIELD ) 
R R R R R R R 

2 R 



QAlEWfield,i,j) computes the d'Alembertian of the ij - component of the rank 2 
tensor field. 



YT(f,m,n) computes the m,n component of the Yllmaz tensor defined by 

t m " - -2<a m f a *> &V - (l/2)*/^f a k> Vb*) 

♦ d^^f- (1/2)1/^4^ 

where f is the trace of f a b and repeated indices are summed. This reduces 
to the Newtonian stress-energy tensor. 
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[1 1.2] Indicia! Tensor Manipulation 



In ITENSR a tensor is represented as an "indexed object" . This is a function 
of 3 groups of indices which represent the covariant, contravariant and derivative 
indices. The covariant indices are specified by a list as the first argument to the 
indexed object; the contravariant indices are specified by a list as the second 
argument. If the indexed object lacks either of these groups of indices, then the 
empty list, [], is given as the corresponding argument For example, 

GK[mu,nu],[]) 
represents an indexed object called G which has covariant indices mu,nu and no 
contravariant or derivative indices. 

The derivative indices, if they are present, follow as additional arguments to 
the (symbolic) function representing the tensor. They are usually not explicitly 
specified by the user but are created in the process of differentiation with 
respect to some coordinate variable. A derivative index is not the coordinate 
variable itself, but rather the coordinate index. These indices are appended as 
additional arguments to the function representing the tensor. Since it is assumed 
that ordinary differentiation is independent of the order in which it is carried out, 
the derivative indices are sorted alphabetically. This canonical order makes it 
possible for MACSYMA to recognize that, for example, T([mu],[nu],i,j) is the same 
as T([mu],[nu]J,i). Differentiation of an indexed object with respect to some 
coordinate whose index does not appear as an argument to the indexed object 
would normally yield zero since MACSYMA would not know that the tensor 
represented by the indexed object might depend implicitly on the corresponding 
coordinate. This has been remedied by modifying the existing MACSYMA function 
DIFF so that in the tensor package it assumes that all indexed objects depend on 
any variable of differentiation unless otherwise stated. This makes it possible for 
the summation convention to be extended to derivative indices. 

To specify that an indexed object is independent of all coordinate variables, it 
is specified a constant by using the DECLARE function (see 8.1). Usually, 
DIFF(W([],[I,J]),K) results in W([],[I,J],K); if the command DECLARE(W,CONSTANT) 
had previously been given, the result of the differentiation would be 0. 

The following functions are available in the tensor package for manipulating 
indexed objects. At present it is assumed that all tensor indices are completely 
symmetric. 

In what follows, general indexed objects will be denoted tensor, 
tensor l,ten$or2,... . The letters L1,L2,... denote lists which are arguments to 
indexed objects. Optional arguments are enclosed in angle brackets. 
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SHOWTENfexp/l will display exp with the indexed objects in it shown having 
covariant indices as subscripts.contravariant indices as superscripts. The 
derivative indices will be displayed as subscripts, separated from the 
covariant indices by a comma. 



COMPONENTS! tensor,exp) permits one to assign an expression exp giving the 
values of the components of tensor. These are automatically substituted for 
the tensor whenever it occurs with all integer indices. 

The tensor must be of the form T([...],[...]), which can specify a covariant 
(second list empty), contravariant (first list empty), or mixed (neither list 
empty) tensor, exp can be a matrix, an array or any expression (except a 
single variable) involving other tensors. 

If exp is a matrix, then tensor must have exactly two indices. If it is an 
array, then exp and tensor must have the same number of indices. If exp is 
some other expression involving tensors, then it must have the same free 
indices as tensor. This expression will be used even if the indices are not 
integers. 

(CI) COMPONENTS(G([I,0],[]),HATRIX)S 

(C2) COHPONENTS(G([],[J,K]),ARRAY)S 

<C3) COMPONENTS(E([I].[J]),6([I.K])»H([],[IC,03))1 

Thus, the various covariant, contravariant, and mixed components of the same 
tensor (for example, Q above) can be specified using COMPONENTS several 
times. The appropriate components will be chosen when required in a 
computation. 



\NDEX£D( tensor) must be executed before assigning components to a tensor for 
which a built in value already exists as with CHR1, CHR2, RIEMANN. 



REMCOMPSrtensor; unbinds all values from tensor which were assigned with the 
COMPONENTS function. 
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INDICESfexpJ returns a list of two elements. The first is a list of the free indices 
in exp (those that occur only once); the second is the list of dummy indices in 
exp (those that occur exactly twice). 



RENAMEfexp, <count>) returns an expression equivalent to exp but with the 
dummy indices in each term chosen from the set [#1, #2,...], if the optional 
second argument is omitted. Otherwise, the dummy indices are indexed 
beginning at the value of count Each dummy index in a product will be 
different; for a sum, RENAME will try to make each dummy index in a sum the 
same. In addition, the indices will be sorted alphanumerically. 

DUMMY<7/,/2,.„; will set each index il,i2,... to name of the form *n where n is a 
positive integer: This guarantees that dummy indices which are needed in 
forming expressions will not conflict with indices already in use. 
C0UNTER[1] determines the numerical suffix to be used in generating the 
next dummy index. The prefix is determined by the option DUMMYX[#]. 

QEFCON(tensorl,<ten$or2,ten$or3>) gives tensorl the property that the 
contraction of a product of tensor! and ten$or2 results in ten$or3 with the 
appropriate indices. If only one argument, tensorl, is given, then the 
contraction of the product of tensorl with any indexed object having the 
appropriate indices (say tensor) will yield an indexed object with that 
name,i.e. tensor, and with a new set of indices reflecting the contractions 
performed. 

For example, if METRIC: G, then DEFCON(G) will implement the raising and 
lowering of indices through contraction with the metric tensor. 

More than one DEFCON can be given for the same indexed object; the 
latest one given which applies in a particular contraction will be used. 

CONTRACTIONS is a list of those indexed objects which have been given 
contraction properties with DEFCON. 



D\$PC0N( tensorl, tensor 2,...) displays the contraction properties of the tensori as 
were given to DEFCON. DISPCON(ALL) displays all the contraction properties 
which were defined. 
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REMCOW tensor 1 ,ten$or2,.J removes all the contraction properties from the 
tensor/. REMCON<ALL) removes all contraction properties from all indexed 
objects. 



CONTRACTfexp) carries out all possible contractions in exp, which may be any 
well-formed combination of sums and products. This function uses the 
information given to the DEFCON function. Since all tensors are considered to 
be symmetric in ail indices, the indices are sorted into alphabetical order. 
Also all dummy indices are renamed using the symbols *1,#2,... to permit the 
expression to be simplified as much as possible by reducing equivalent terms 
to a canonical form. For best results exp should be fully expanded 
RATEXPAND (see 6.1.1) is the fastest way to expand products and powers of 
sums if there are no variables in the denominators of the terms. The 
TAKEGCD switch should be FALSE if gcd cancellations are unnecessary. 



CANTENfexp,* reduces exp to a canonical form and simplifies the expression as 
much as possible by renaming and permuting dummy indices. The expression 
exp must be fully expanded. 

As an example of the kind of simplification this function achieves, consider the 
following sum of tensor "monomials'*: 



<C4) P(CI,J,S,V3,[H f N,Q],V)*Pl(CQ,T] f [R,S])*P2([R,L.H f N t U],[I,J,IC]) + 

P2([L.N,U],[R,H,I t 0,K])*P([H,I,J,V],[N,0.S] r V)*Pl([R,S t Q,T],[])S 

(C6) SH0WTEN(D4); 

RHIOK NQS HNQ RS I J K 

(E6) P2 P PI ♦ P PI P2 

LNU MIJV.V RSQT I J S V,V QT RLHNU 

(06) E6 



Recall that all these indexed objects are assumed to be completely symmetric 
in their indices. The function RENAME renames the dummy indices: 
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(C7) SH0WTEN(RENAHE(D4))i 



#6 #7 #8 #2 #3 K #4 #5 

(E7) P P2 PI 

#1 #2 #3 #5,#1 #4 #6 #7 L U #8 T 



#3 #4 #8 #2 #5 #6 #7 K 

♦ P PI P2 

#1 #5 #6 #7,#1 #2 #3 #4 T #8 L U 



but is not able to notice that by a sequence of raising and lowering 
operations, the original expression can be transformed into 

<C8) SH0WTEN(CANTEN(D4))t 

K IJNNQRS 

(E8) 2 P2 P Pi 

IJLHNRU QSV.V T 



METRICCQ specifies the metric by assigning the variable METRIQ-.G; in addition, 
the contraction properties of the metric G are set up by executing the 
commands DEFCON* G), DEFCON(G,G,KDELTA). 



CHR1 ([i,j,k]) yields the Christoffel symbol of the first kind 

<&ik,j + gjk,i -gij,k>/ 2 

The variable METRIC must be assigned the name of a function (which can be 
either defined or undefined); in the above example, METRIC:g. 

CHR2([i,j],[k]) yields the Christoffel symbol of the second kind. 

CHR2([i,Jl[k]) = g k8 CHRl<[iJ,sJ 
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LC(U is the permutation (or Levi-Civita) tensor which yields 1 if the list L 
consists of an even permutation of integers, -1 if It consists of an odd 
permutation, and if some indices in L are repeated 

KDELT A(L1,L2) is the generalized Kronecker delta functioa LI and L2 are lists of 
indices of the same length. 

a) If Li and £2 have a single member, say Ll=[a] and L2*=[b]. Then 

1) if the index a is identical to the index b and they are non- 
numeric, the value of the function KDELTA is the value of the 
variable DIMENSION^] ; 

2) if a and b are numeric then the value of the function is 1 if they 
are equal, else 0; 

3) otherwise the noun form of KDELTA. 

b) If Ll=[al,a2] and L2=[bl,b2J Then the value of the function is 

KDELTA([al].[bl])*KDELTA([a2J,[b2]) 

- KDELTA([al],[b2])*KDELTA([a2],[bl]) 

c) If LI and L2 have more than two indices the result generalizes. 

RIEMANN([/,;;fcJ[/]; yields the Riemann curvature tensor in terms of the Christoffel 
symbols of the second kind (CHR2). 

Suppose the name specified by the value of METRIC corresponds to a tensor 
which has been given some structure via the COMPONENTS command above; 
in order to evaluate an expression involving the Riemann tensor and 
incorporate this given structure of the metric explicitly into the result, the 
user can simply do express/on,EVAL. 

Consider the following example involving a metric, G, expressed in terms of 
the rank two tensors, P and E. First, the covariant and contravariant forms of 
the metric are specified; 
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(C9) COMPONENTS(G([M,N],[]) f 

E([M,N],[]) ♦ U(2*P(t].C])*E(CH.N],[])-4*P([M f N],[])) 
L~2*(2*P([ ],[ ]r2*E([h\N],[ ]) 

- 8*P(C],C])*P([H,N] t C])*8*P([H].[Q])*P([0,N].[])))t 

(CIO) COMPONENTS(G([],[H,N]), 

E([].[M,N]) - U(2*P(U,[])*E([],[H,N])-4*P([L[M.N])) 
♦ L*2*(2*P([],[]r2*E<[J,[H,N]) 

- 8*P([],[3) # P([],[H,N3H8«P([] f CM,Q])*P([Q] f CN])))t 

(Cll) SHWTEN(G([A,B],[]))t 

Z Q 2 

(Ell) L (8 P P -8PP *2P E ) ♦ L (2 P E . • 4 P ) 
A Q B AB A B AB AB 



♦ E 
AB 
(C12) SH0WTEN(6([],[R,S])); 

2 RQS RS 2 R S RSRS 

(E12) L(8P P-8PP +2PE ) - (2 P E -4P )L 
Q 

RS 
♦ E 
(C13) (RATVARS(L),RATWEIGHT(L,l),RATVTLVL:2)i 

The above metric is an expansion to second order of the Yiimaz exponential 
metric 

G s E e 2*L*(I.P - 2*P) 

where L is an expansion parameter, P is a rank two tensor field viewed as a 
matrix whose components are P^ and whose trace is P. 

To second order, the covariant and contravariant forms of the metric 
should be mutually inverse. As an example of the contraction and 
simplification functions CONTRACT,CANTEN one can verify this as follows: 
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(CM) SHOWTEN(EX:CONTRACT(RATEXPAN0(G([H,R],[])*G(£],[R.N]))))t 

N N 2 #1 #1 N 2 

(E14) KDELTA + 16 P LP - 16 P P L 

M #1 M #1 M 



Because RATWTLVL2, the product of the expansions is truncated? the second 
order terms are actually equal and should cancel. Using a canonical form, the 
function CANTEN makes the appropriate simplification which enables the last 
two terms to be compared and cancelled: 

(C16) SHOWTEN(CANTEN<EX)); 

N 
(E16) KDELTA 

M 



The Ricci tensor is easily expressed in terms of the Riemann tensor, 
using the Einstein summation convention: 



(C18) RICCI :RIEHANN([I,J,K],[K})$ 
(C19) %,EVALS 

( C20 ) EXP 1 : C0NTRACT( RATEXPAND( RICCI ) )$ 
(C21) SHOWTEN(FACTOR(EXPl))t 

#1 #1 #2 

(E21) ~ (2 P - 2 E P 

J,#l I I J,#l #2 

#1 #2 #1 

♦ P E E*2P )L 
,#1 #2 I J I,#l J 
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D\FF(exp,vl f nl,v2 f n2 r J is the usual MACSYMA differentiation function; it takes 
the derivative of exp wrt vl n! times, wrt v2 n2 times, etc. For the tensor 
package, the following modifications have been incorporated: 

1) the derivatives of any indexed objects in exp will have the variables 
vi appended as additional arguments. Then all the derivative indices will be 
sorted. 

2) the vi may be integers from 1 up to the value of the variable 
DIMENSION^]. This will cause the differentiation to be carried out wrt the 
v/th member of the list COORDINATES which should be set to a list of the 
names of the coordinates, e.g., [x,y,z,t] . If COORDINATES is bound to an 
atomic variable, then that variable subscripted by vi will be used for the 
variable of differentiation. This permits an array of coordinate names or 
subscripted names like X[l], X[2],... to be used. If COORDINATES has not 
been assigned a value, then the variables will be treated as in 1) above. 

C0VD\FF(exp,vl,v2 r ..) yields the covariant derivative of exp with respect to the 
variables vi in terms of the Christoffel symbols of »K« e<^ G r^ i,;^ /ruoo\ i« 
order to evaluate these, one can use exp, eval or EV(exp,CHR2). 

UNDIFFfexp; returns an expression equivalent to exp but with all derivatives of 
indexed objects replaced by the noun form of the DIFF function with 
arguments which would yield that indexed object if the differentiation were 
carried out. This is useful when it is desired to replace a differentiated 
indexed object with some function definition and then carry out the 
differentiation by saying EV(...,DIFF). 



LORENTZfexp; yields exp replacing by zero those indexed objects which have a 
derivative index identical to a contravariant index. This imposes the Lorentz 
condition. 



MAKEBOXfexp; will display exp in the same manner as SHOWTEN; however, any 
tensor d'Alembertian occurring in exp will be indicated using the symbol [] 
For example, []P([M],[N]) represents G<[],[I,J])*P([M}[N],I,J). 
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ZERQ(tensor) will give tensor a property such that the 

command FLUSHf expression) will, in expression, replace by zero a!! 
occurences of the tensor involving derivative indices. 
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12 The SHARE Directory 



The SHARE directory contains programs, information files, etc. which are 
considered to be of interest to the MACSYMA community. Most files on SHARE; 
are not part of the MACSYMA system per se and must be loaded individually by 
the user, e.g. LOADFILE(ITENSR,FASL,DSK,SHAREb. Many files on SHARE; were 
contributed by MACSYMA users, and all MACSYMA users are encouraged to do so. 

Names for files on SHARE; should be chosen as appropriate. However, the 
contributor will probably want to follow the conventions discussed here. A 
contributor will probably create some but not all of the following files. Examples 
may be seen on the SHARE directory. 

1) NAME > is the file name of the MACSYMA BATCHable programs. The > 
sign indicates a numeric second filename which is increased whenever a new 
version is created. 

2) NAME LISP is the file name of the LISP code for the programs contained in 

tho file. MAMP > Thie filo ie InartaA mt« UAPCVMA iicins I OAnril T It i./=»e 

obtained by using the TRANSLATE command or was written directly in LISP by the 
contributor. 

3) NAME FASL is the file name of the FASL (fast-loadable) version of NAME 
LISP, and was produced from NAME LISP by using the LISP compiler. It is loaded 
into MACSYMA using the LOADFILE command 

4) NAME USAGE is the name of the documentation file for the programs in 
NAME >. It describes how the programs are used, inputs, outputs, options, 
warnings, error messages, etc. It may mention the algorithms behind the programs, 
references, and whatever else the user should know. It should certainly indicate 
who programmed the routines, especially his login name. If the NAME USAGE file 
does not exist, this information should be given in NAME > or elsewhere. 

5) NAME DEMO is the name of the demonstration file which may be used in 
DEMOing NAME > or NAME LISP. 

6) NAME OUTPUT may be used to store sample output obtained from running 
NAME > on some examples or from DEMOing the NAME DEMO file. 

7) Other file names may be used for information files providing some 
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information on some aspect of the MACSYMA system or for describing some 
MACSYMA utility or for notes on some MACSYMA issues, etc. 

ThiP» £HARF > filo ie an inHav l/> tk*» CUADr j4;.. e ,a M ».w ~~*J :*. l.t..J«J ». 
..._ „......;_ ,„ w ,„ W1I imviwA «v %ii«5 01 irtitu uiicwivi j chiu ia iiiicmucu iu 

contain a short note on each of the programs on the SHARE directory, it should 
be updated by the SHARE; contributor as appropriate. 

Any comments or questions about the use of the SHARE directory should be 
sent to JPG. 



1 2. 1 Simplification for ABS and SIGNUM 



The file SHARE;ABSIMP > contains MACSYMA pattern-matching rules that 
extend the built-in simplification rules for the ABS and SIGNUM functions. Among 
other things, use is made of global relations established with the built-in ASSUME 
function or by declarations such as DECLARE(M,EVEN, N,0DD) for even or odd 
integers. UNITRAMP and UNITSTEP functions are also defined in terms of ABS 
and SIGNUM. These routines were written by David Stoutemyer. 



[12.2] Array Manipulation 

The file ARRAY FASL provides various utility functions for handling arrays. 

LISTARRAYfarray) returns a list of the elements of a declared array, the order is 
row-major. You will get garbage if any of the elements have not been 
defined yet. 



FILLARRAYferray^/sf-or-arrayJ fills array from list-or-array. If array is a floating- 
point (integer) array then list-or-array should be either a list of floating-point 
(integer) numbers or another floating-point (integer) array. If the dimensions 
of the arrays are different array is filled in row-major order. If there are not 
enough elements in list-or-array the last element is used to fill out the rest 
of array. If there are too many the remaining ones are thrown away. 
RLLARRAY returns its first argument. 
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REM*RM(array,diml, ... ,dimk) can be used to change the size or dimensions of an 
array. The new array will be filled with the elements of the old one in row- 
major order. If the old array was too small, FALSE, 0.0 or will be used to 
fill the remaining elements, depending on the type of the array. The type of 
the array cannot be changed. 



ARRAYAPPLYfcrray/su&J, ... ,subkj) is like APPLY except the first argument is an 
array. 

These routines were written by Charles Karney. 

[ 1 2.3] Solving Differential Equations by Laplace Transforms 

DESOLN LISP contains a routine, written by Richard Bogen, for solving 
differential equations or systems of them by using Laplace transforms. The call is: 

OESQLVE([eql,...,eqn],[varl,...,varnJ) where the e<fs are differential equations in 
the dependent variables varl,...,varn. The functional relationshiprmusfbe 
explicitly indicated in both the equations and the variables. For example 

(CI) 'DIFF(F,X,2)=SIN(X)+'DIFF(G,X); 
(C2) 'DIFF(F,X)+X A 2-F=2*'DIFF(G,X,2); 

is not the proper format. The correct way is: 

(C3) 'DIFF(F(X),X,2)=SIN(X)+'DIFF(G(X),X); 
(C4) 'DIFF(F(X),X)+X*2-F(X)=?*'DIFF(G(X),X,2); 

The quotes are not necessary since DIFF will return the noun forms 
anyway. 

The call is then DES0LVE([D3,D4],[F(X) I G(X)]); 

If initial conditions at are known, they should be supplied before calline 
DESOLVE by using ATVALUE. 

(Cll) 'DIFF(F(X),X)='DIFF(G(X),X)+SIN(X); 
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D 

(Oil) — F(X) = — G(X) ♦ SIN(X) 

DX DX 

(C12) 'DIFF(G(X),X,2)='DIFF(F(X),X)-COS(X); 

2 

D 

(012) — G(X) = - F(X) - COS(X) 

2 DX 

DX 
(C13) ATVAIUE('DIFF(G(X),X),X=0,A); 

(013) A 

(C14) ATVALUE(F(X).X*0,1); 

(D14) 1 

(C15) DESOLVE([Dll,D12] f [F(X),G(X)]); 

X X 

(D16) [F(X)=A XE - A+l, G(X) * COS(X) ♦ A XE - A ♦ G(0) - 1] 

/* VERIFICATION */ 
(C17) [D11,D12],D16,DIFF; 

XXX X 

(D17) [A XE = A XE f A XE - COS(X) * A XE - COS(X)] 



1 2.4 Exterior Calculus of Differential Forms 

The exterior calculus of differential forms is a basic tool of differential 
geometry developed by Elie Cartan and has important applications in the theory of 
partial differential equations. The present implementation is due to F.B. Estabrook 
and H.D. Wahlquist. The program is self-explanatory and can be accessed by 
doing 

BATCH<[CARTAN,START,DSK,SHARE10N) 
which will give a description with examples. 
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The next six sections describe programs written by David Stoutemyer. 

12.5 Vector Analysis 

The file VECT > contains a vector analysis package, VECT DEMO contains a 
corresponding demonstration, and VECT ORTH contains definitions of various 
orthogonal curvilinear coordinate systems. 

The vector analysis package can combine and simplify symbolic expressions 
including dot products and cross products, together with the gradient, divergence, 
curl, and Laplacian operators. The distribution of these operators over sums or 
products is under user control, as are various other expansions, including 
expansion into components in any specific orthogonal coordinate systems. There 
is also a capability for deriving the scalar or vector potential of a field. 

To establish indeterminate 1, indeterminate2, ... as vector entities, type 

DECLARER indeterminate 1, indeterminate2, ...], NONSCALAR) S 

Vectors can also be represented as lists of components. 

"." is the dot-product operator, "~" is the cross-product operator, GRAD is 
the gradient operator, DIV is the divergence operator, CURL is the curl or rotation 
operator, and LAPLACIAN is DIV GRAD. 

Most non-controversial simplifications are automatic. For additional 
simplification, there is a function which can be used in the form 

VECTORSIMP(Vecforexpress/on; 

This function employs additional non-controversial simplifications, together with 
various optional expansions according to the settings of the following global flags: 

EXPANDALL, EXPANDDOT, EXPANDDOTPLUS 

EXPANDCROSS, EXPANDCROSSPLUS, EXPANDCROSSCROSS 

EXPANDGRAD, EXPANDGRADPLUS, EXPANDGRADPROD 

EXPANDDIV, EXPANDDIVPLUS, EXPANDDIVPROD 
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EXPANDCURL, EXPANDCURLPLUS, EXPANDCURLCURL 

EXPANDLAPLACIAN, EXPANDLAPLACIANPLUS, EXPANDLAPLACIANPROD 

Al! these flags have default value FALSE. The PLUS suffix refers to employing 
additivity or distributivity. The PROD suffix refers to the expansion for an 
operand that is any kind of product. EXPANDCROSSCROSS refers to replacing 
p-(q-r) with (p.r)*q-(p.q)*r, and EXPANDCURLCURL refers to replacing CURL CURL 
p with GRAD DIV p + DIV GRAD p. EXPANDCROSS:TRUE has the same effect as 
EXPANDCROSSPLUS:EXPANDCROSSCROSS:TRUE, etc. Two other flags, 
EXPANDPLUS and EXPANDPROD, have the same effect as setting all similarly 
suffixed flags true. When TRUE, another flag named 

EXPANDLAPLACIANTODIVGRAD, replaces the LAPLACIAN operator with the 
composition DIV GRAD. All of these flags are initially FALSE. For convenience, all 
of these flags have been declared EVFLAG. 

For orthogonal curvilinear coordinates, the global variables 
COORDINATES[[X,Y,Z]], DIMENSION^], SFt[l t l,l]l and SFPR0D[1] are set by the 
function invocation 

SCALEF bCTORS(coordmatetran$form) 

Here coordinatetrans form evaluates to the form [[expression 1, expression2, ...], 
indeterminate!, indeterminat2, ...], where indeterminate 1, indeterminate2, etc. are 
the curvilinear coordinate variables and where a set of rectangular Cartesian 
components is given in terms of the curvilinear coordinates by [expressionl, 
expression2, ...]. COORDINATES is set to the vector [indeterminate 1, 
indeterminate2, ...], and DIMENSION is set to the length of this vector. SF[1], 
SF[2], .... SFfDIMENSION] are set to the coordinate scale factors, and SFPROD is 
set to the product of these scale factors. Initially, COORDINATES is [X, Y, Z], 
DIMENSION is 3, and SF[1]=SF[2]=SF[3]=SFPR0D=1, corresponding to 3- 
dimensional rectangular Cartesian coordinates. 

To expand an expression into physical components in the current coordinate 
system, there is a function with usage of the form 

E X P R E S S (expression) 

The result uses the noun form of any derivatives arising from expansion of the 
vector differential operators. To force evaluation of these derivatives, the built- 
in EV function can be used together with the DIFF evflag, after using the built-in 
DEPENDS function to establish any new implicit dependencies. 
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The scalar potential of a given gradient vector, in the current coordinate 
system, is returned as the result of POTEm\M(givengradient) 

The calculation makes use of the global variable POTENTIALZEROLOC[0], which 
must be NONLIST or of the form [indeterminatej=expressionj, 
mdeterminatek=expressionk, ...], the former being equivalent to the noniist 
expression for all right-hand sides in the latter. The indicated right-hand sides 
are used as the lower limit of integration. The success of the integrations may 
depend upon their values and order. POTENTIALZEROLOC is initially set to 0. 

The vector potential of a given curl vector, in the current coordinate system, 
is returned as the result of 

VECTORPOTENTIALfe/verax/r/; 

POTENTIALZEROLOC has a similar role as for POTENTIAL, but the order of the 
left-hand sides of the equations must be a cyclic permutation of the coordinate 
variables. 

EXPRESS, POTENTIAL, and VECTORPOTENTIAL can have a second argument 
like the argument of SCALEFACTORS, causing a corresponding invocation of 
SCALEFACTORS before the other computations. 



12.6 Dimensional Analysis 



The file DIMEN > contains functions for automatic dimensional analysis, and file 
DIMEN DEMO contains a demonstration. Usage is of the form 

NONDIMENSIONAUZE<y/sf of physical quantities) 

The returned value is a sufficient list of nondimensional products of powers of 
the physical quantities. A physical relation between only the given physical 
quantities must be expressible as a relation between the nondimensional 
quantities. There are usually fewer nondimensional than physical quantities, which 
reduces the number of experiments or numerical computations necessary to 
establish the physical relation to a specified resolution, in comparison with the 
number if all but one dependent physical variable were independently varied. 
Also, the absence of any given physical quantity in the output reveals that either 
the quantity is irrelevant or others are necessary to describe the relation. 
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The program already knows an extensive number of relations between 
physical quantities, such as VELOCITY=LENGTH/TIME. The user may over-ride or 
supplement the prespecified relations by typing 

Q\MENS\QN(equaiion or iisi of equations) 

where each equation is of the form indeterminate=expression, where expression 
is a product or quotient of powers of none or more of the indeterminates 
CHARGE, TEMPERATURE, LENGTH, TIME, or MASS. To see if a relation is already 
established type 

GET(indeterminate, 'DIMENSION); 

The result of NONDIMENSIONALIZE usually depends upon the value of the 
global variable 7oPURE, which is set to a list of none or more of the indeterminates 
ELECTRICPERMITTIVITYOFAVACUUM, BOLTZMANNSCONSTANT, SPEEDOFLIGHT, 
PLANCKSCONSTANT, GRAVITYCONSTANT, corresponding to the relation between 
charge and force, temperature and energy, length and time, length and momentum, 
and the inverse-square law of gravitation respectively. Each included relation is 
used to eliminate one of CHARGE, TEMPERATURE, LENGTH, TIME, or MASS from 
the dimensional basis. To avoid omission of a possibly relevant nondimensional 
grouping, either include the relevant constant in 7.PURE or in the argument of 
NONDIMENSIONALIZE if the corresponding physical effect is thought to be relevant 
to the problem. However, the inclusion of unnecessary constants, especiaHy the 
latter three, tends to produce irrelevant or misleading dimensionless groupings, 
defeating the purpose of dimensional analysis. As an extreme example, if all five 
constants are included in XPURE, all physical quantities are already dimensionless. 
7.PURE is initially set to '[ELECTRICPERMITTIVITYOFVACUUM, 

BOLTZMANNSCONSTANT], which is best for most engineering work. 7.PURE must 
not include any of the other 3 constants without also including these 2. 



[1 2.7] Analytic Optimization 



We now describe a package for finding the stationary points of a multivariate 
objective function, either unconstrained or subject to equality and/or inequality 
constraints. 

RELEVANT FILES: OPTMIZ > is a MACSYMA batch file containing the functions and 
option settings for optimization. OPTMIZ DEMO is a MACSYMA batch file 
demonstrating various ways of using the optimization functions. OPTMIZ OUTPUT is 
a text file listing OPTMIZ DEMO together with the output that it produces when 

executed. 
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To use this package from a MACSYMA, first type BATCH(OPTMIZ, ">", DSK, 
SHARE) Then the following command is available: 

ST kP(OBJECTIVE, LEZEROS, EQZEROS, DECISIONVARS) 

OBJECTIVE is an expression denoting the objective function or the label of 
such an expression. LEZEROS is a list, of expressions which are constrained to be 
less than or equal to zero. Use [] if no such constraints. EQZEROS is a list of 
expressions which are constrained to equal zero, or the label of such a list. Use 
[] if there are no such constraints. DECISIONVARS is a list of the decision 
variables or the label of such a list. One may use [] if all variables in objective 
and constraintsare decision variables. For convenience, brackets may be omitted 
from one-expression lists, and trailing [] arguments may be omitted. 

ROOTSEPSILON may affect the accuracy of results computed by SOLVE and 
REALROOTS within STAP. The default value of 1.0E-7 for this MACSYMA global 
variable is as small as practical for pdp single-precision floating-point arithmetic. 
Larger values save cpu time. 

The class of functions that may be used and the practical limitations on the 
number of decision variables and constraints is primarily dependent upon the 
capabilities of the built-in SOLVE function, which is still under development. 



[ 1 2.8] Variational Optimization 



This section describes how to use a MACSYMA variational optimization 
package to analytically solve problems from the calculus of variations and the 
maximum principle, including optimal control. 

To use this package in a MACSYMA, first type BATChKOPTVAR,"^, DSK, 
SHARE) or LOADFILE(OPTVAR, LISP, DSK, SHARE). 

To derive the Euler-Lagrange equations for a calculus-of-variations problem, 
type 

EL(F, YLIST, TUST) 

F is an expression or the label of an expression for the integrand of the 
stationary functional, augmented by Lagrange multipliers times the integrands of 
any isoperimetric constraints and/or differential expressions constrained to equal 
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zero. The multipliers should be written as functions of the independent variables 
in the latter case. 

YLIST is a list of the dependent variables, or the label thereof. 
TLIST is a list of the independent variables, or the label thereof. 

For convenience, square brackets may be omitted from 1 -element lists. EL 
displays one or more E-labeled equations, then returns a list of the E-labels. 
These equations are the Euler-Lagrange equations, perhaps together with first 
integrals corresponding to conservation of energy and/or conservation of 
momentum. The former will contain a constant of integration K[0], whereas the 
latter will contain constants of integration Kfll with positive I. The latter will 
immediately follow the corresponding Euler-Lagrange equation. 

OPTVAR DEMO or OPTVAR OUTPUT illustrates some ways that the resulting 
differential equations may be solved analytically. 

To derive the Hamiltonian and auxiliary differential equations for an optimal 
control problem, type 

HkWODES) 

ODES is a list of the first-order differential equations that govern the state 
variables. Each differential equation must be of the form 

'D(Y.T) = EXPRESSION 

where Y is one of the dependent variables, T is the independent variable, and 
EXPRESSION depends upon the independent, dependent, and control variables. 

HAM displays two or more E-labeled expressions, then returns a list of the 
E-labels The first expression is the Hamiltonian, and the other expressiona are 
the auxiliary deferential equations, together with their general solutions, AUX[I] = 
K[l], whenever the Ith differential equation is of the trivial form 'D(AUX[I],T) = 0. 
The K[l] are undetermined constants of integratioa 

HAM is directly suitable for the autonomous time-optimal problem. Other 
problems may be converted to this form by introducing extra state variables, as 
described in most optimal-control texts or in the report referenced in OPTVAR 
OUTPUT and OPTVAR DEMO. 
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[12.9] Qualitative Analysis 

QUAL > contains MACSYMA functions for qualitative analysis of an expression, 
QUAL DEMO contains a demonstration, and QUAL OUT contains the output from 
executing the demo. 

To use the functions do ALL0C<2); LOADFILECSTOUTE/'^DSK.MRG); 
BATCH(QUAL, ">", DSK, SHARE); 

Top-level usage is of the form Qi)M(<expre$sion>, <variabfe$>) 

where <expression> is any given expression, <variables> is a given indeterminate 
or list of indeterminates. !f omitted, this argument defaults to all of the 
inde terminates in the first argument. 

QUAL returns a list of E-labels of displayed equations, each of the form 
<property name> s <property value> 

where <property name> is one of the second-level function names below, and 
<property value> is the value returned by that function. These second-level 
functions may also be used directly. Usage is of the form 

REVELATION(<expression>, <m1n1mum>, <max1mum>); 
BOUNDS(<expression>); 
SLOPES(<expressi.on>, <variab1es>); 
CURVATURE«expression>, <var 1ables>) ; 
SYMMETRY(<expression>, <variables>) ; 
PERIODS(<expression>, <variables>); 
ZEROSANDPOLES(<expression>, <var1ables>) ; 
STATI0NARYP0INTS(<express1on>, <var1ables>) ; 
LIMITS(<express1on>, <var 1ables>) ; 

where <expression>, <variables>, and their defaults are as for QUAL 
[ 1 2. 1 0] Units Conversion 



The file UNITS > contains assignments for automatic conversion to MKS metric 
units. Usage example: 5*FT + METER + CM; simplifies to 2.534*METER . 
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Erroneously dimensionally inhomogeneous expressions are revealed by 
uncollected terms. For example, 5*FT + SECOND; does not simplify to one term. 

The supplied conversions comprise a rather complete set, but it should be 
clear how to supplement them or produce an anaiagous set for conversion to 
other units. 



[ 1 2. 1 1 ] The Eigen Package 



The BATCH file EIGEN > contains a package of functions is written in top- 
level MACSYMA. Its purpose is to compute right eigenvectors, right unit 
eigenvectors, eigenvalues, and similarity transforms. NOTE: This package 
currently will not handle systems with multiple eigenvalues Implementation of tNs 
capability will await the ability to handle multiple roots from SOLVE 



EVEC 1 (M t mu,modes) computes right eigenvectors of the matrix M t given the 
eigenvalues mm mu is a one dimensional array of the eigenvalues of M. 
modes* is the order of the system EVECl returns a list of lists which are 
the eigenvectors; i.e., it returns a list of sublists, each of wNch contains the 
components of an eigenvector. 



E\JEC2( M,mu,mode$) is exactly the same as EVECl except that it constructs the 
list of eigenvectors differently from EVECl. It is a toss-up as to which is 
faster. 



INPRODfoy; computes the real inner product of two lists (not vectors). This inner 
product is the sum of the products of the respective components of the lists. 
The two lists used as arguments to INPROD must be of the same length. 

UE\/EC(M,mu,modes) computes the unit eigenvectors of the matrix M. That is, the 
eigenvectors are of unit length as defined by INPR0D(x ( x). UEVEC merely 
calls evecl to compute the eigenvectors, and then calls INPROD to compute 
the length of each eigenvector in turn and divides by this length. UEVEC 
returns a list of vectors (not lists) which are the unit eigenvectors. Since 
UEVEC calls EVECl, the eigenvalues mu (defined as in EVECl) must be 
distinct. 
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£MMS(mat,lambda) computes the eigenvalues of the matrix mat and stores them 
in the one dimensional array lambda. It returns the value "done". The array 
lambda must be set up as an array before the call to EVALS. Also, this 
function will not handle multiple eigenvalues. 



SIMTRANfmat) is the function which computes the similarity transformation 
mentioned above, it merely calls the other functions such as EVALS, UEVEC, 
etc. to determine the eigenvalues and right unit eigenvectors. For a 
symmetric matrix with distinct eigenvalues, the matrix formed by taking the 
unit eigenvectors as columns is an orthogonal matrix, as is its transpose. Thus 
if A is the original symmetric matrix (with distinct eigenvalues) and Q is the 
orthogonal matrix constructed as above, and QT is the transpose of Q, then 

QT*A*Q = D 

where D is the diagonal matrix with the eigenvalues of A on the diagonal. 
SIMTRAN takes the matrix mat and fills the global array lambda with the 
eigenvalues of mat It also fills the globally defined matrices Q and QT with 
the matrices Q and QT as described above. 

The array lambda and the matrices Q and QT must exist as an array and 
matrices (presumably loaded with dummy info) before the call to SIMTRAN. 
The matrix mat should not have multiple eigenvalues for the reasons 
mentioned in previous comments. 



[12.12] Elimination by Resultants 



ELIM LISP contains a program, written by Richard Bogen, for eliminating 
variables from equations (or expressions assumed equal to zero) by taking 
successive resultants, the call is: 

ElM\UtKlE([eql,eq2,...,eqn],[vl,v2,...,vk]) 

This returns a list of n-k expressions with the k variables vl,...,vk eliminated. 
First vl is eliminated yielding n-1 expressions, then v2 is, etc. If k=n then a 
single expression in a list is returned free of the variables vl,...,vk. In this case 
SOLVE is called to SOLVE the last resultant for the last variable. If there are 
floating point numbers in the input expressions then KEEPFLOAT:TRUE should be 
done so as not to have them rationalized in taking the resultant. 
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EXAMPLE 

(C5) .5*X~4+Y*X*Z; 

4 

(05) Z *X Y ♦ 0.5 X 

(C6) 3*X+5*Y-Z-1; 

(06) -Z*5Y*3X-1 

(C7) Z~2+X*2-Y*2+5; 

2 2 2 

(07) 2 - Y ♦ X +5 

<C8) ELIMINATE([D7,D6.D5],IY,Z]),I<EEPFIQAT:TRUE; 

8 6 5 4 3 2 

(08) [150.0 X - 375.0 X ♦ 50.0 X ♦ 275.0 X ♦ 100 X ♦ 550 X 

♦ 1400 X ♦ 31003 
[ 1 2. 1 3] Integration of Special Forms 



INTSCE LISP contains a routine, written by Richard Bogen, for integrating 
products of sines,cosines and exponentials of the form 

EXP(A*X+B)*COS(C*X) A N*SIN(C*X) A H 

The call is \NTSCE(expr,var) expr may be any expression, but if it is not in 
the above form then the regular integration program will be invoked if the switch 
ERRINTSCE[TRUE] is TRUE. If it is FALSE then INTSCE will err out. 



1 2. 1 4 Integral Equations 



The following package was written by Richard Bogen based on some routines 
of David Stoutemeyer. It is still an experimental version, untranslated and 
uncompiled at present. 

To load the package, do BATCH(INTEQN, ,, > H ,DSK,RAB). 
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CAVEAT; To free some storage, a KILL(LABELS) is included in this file. 
Therefore, before loading the integral equation package, the user should give 
names to any expressions he wants to keep. 

The usage is very simple. The main function is called IEQN. It takes five 
arguments though only the first one is required. If trailing arguments are omitted 
they will default to preset values which will be announced. 

Two types of equations are considered. An integral equation of the second 
kind'is of the form: 

B(X) 
/ 
[ 
(D3) P(X) * Q(X, P(X), I W(X, U, P(X), P(U)) dU) . 

3 
/ 
A(X) 



An integral equation of the first kind is of the form: 

B(X) 

(04) I W(X, U, P(U)) dU = F(X) 

« t 

A(X) 

The unknown function in these equations is P(X) while Q,W,A, and B are given 
functions of the independent variable. Although these are the general forms, most 
of the solution techniques require particular forms of Q and W. 

The techniques used are: 

For SECONDKiND equations. 

FINITERANK: for degenerate (or separable) integrands. 
DIFFEQN: reduction to differential equation. 
TRANSFORM: Laplace Transform for convolution types. 
FREDSERIES: Fredholm-Carleman series for linear equations. 
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TAILOR: Taylor series for quasi-linear variable-limit equations. 
NEUMANN: Neumann series for quasi-second kind equations. 
COLLOCATE: collocation using a power series form for P(X) 
evaluated at eauallv soaced ooints. 

For FIRSTKIND equations: 

FIN1TERANK: for degenerate integrands. 

DIFFEQN: reduction to differential equation. 

ABEL: for singular integrands. 

TRANSFORM: see above 

COLLOCATE: see above 

FIRSTKINDSERIES: iteration technique similar to Neumann series. 

Also, differentiation is used in certain cases to transform a FIRSTKIND into a 
SECONDKIND. 

The calling sequence is 



\£QN(ie,unk,tech,n,gues$) where ie is the integral equation; unk is the unknown 
function; tech is the technique to be tried from those given above (tech = 
FIRST means: try the first technique which finds a solution; tech = ALL means: 
try all applicable techniques); n is the maximum number of terms to take for 
TAYLOR, NEUMANN, FIRSTKINDSERIES, or FREDSERIES (it is also the maximum 
depth of recursion for the differentiation method); guess is the initial guess 
for NEUMANN or FIRSTKINDSERIES. 
Default values for the 2nd thru 5th parameters are: 

unk: P(X), where P is the first function encountered in an 
integrand which is unknown to MACSYMA and X is the variable 
which occurs as an argument to the first occurrence of P found 
outside of an integral in the case of SECONDKIND equations, or 
is the only other variable besides the variable of integration in 
FIRSTKIND equations. If the attempt to search for X fails, the 
user will be asked to supply the independent variable; 
tech; FIRST; 
m 1; 

guess: NONE, which will cause NEUMANN and FIRSTKINDSERIES 
too use F(X) as an initial guess. 

The value returned by IEQN is a list of labels of solution lists. The solution 
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lists are printed as they are found unless the variable IEQNPRINT[TRUE] is 
set to FALSE. These lists are of the form 

[SOLUTION, TECHNIQUE USED, NTERMS, FLAG] 

where FLAG is absent if the solution is exact. Otherwise, it is the word 
APPROXIMATE or INCOMPLETE corresponding to an inexact or non-closed 
form solution, respectively. If a series method was used, NTERMS gives the 
number of terms taken (which could be less than the n given to IEQN if an 
error prevented generation of further terms). 

For examples, do BATCH(INTEXS,">",DSK,RAB) which will load an array called 
EQ with about 43 sample integral equations. Then try IEQN(EQ[l]) f 
IEQN(EQ[30],P(X),ALL), for instance. 



1 2. 1 5 Numerical Techniques 



[ 1 2. 1 5. 1 ] Numerical Integration 



ROMBER is a program for Romberg numerical integration written by Richard 
Fatemaa The calling sequence is ROMBERG(Y,a,fr,//mJ 

where f is a function name (elsewhere, f(x):= .., returns a number which must be 
floating), a and b are limits of integration, and lim is a limit (e.g. 1.0e-4) for the 
accuracy of the answer. ROMBERG computes upper and lower bounds on the 
integral, and goes through a maximum of 10 iterations to satisfy limit, if limit is 
unsatisfied, then it prints error message. It is much better than Simpson's rule, 
and is handier in terms of usage. It may be loaded by 

BATCH(ROMBER,">\DSK, SHARE) 

Also on ROMBER > is Simpson's rule, called by SMPSON(f,a,b,n) 

where n is number of subdivisions, which had better be an even integer, for 
SIMPSON; f, a, and b, (and maybe n), need not be numbers. 

To integrate the exponential function from to 1 to a tolerance of 1.0E-4, 
try ROMBERG(?exp,0,l,1.0E-4); . The time taken is 18 msec (0.018 sec). If one 
uses G(X):=EV(%E"X,NUMER) instead, and does ROMBERG* g,0,l,1.0E- 4); the time is 
still only 150 msec. 
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[ 1 2. 1 5.2] Fast Fourier Transforms 

The following describes some FFT routines written by Tom Knight To load 
the routines do LOADFILE(FFT,FASL,DSK,SHARE); The basic functions are: FFT(Fast 
Fourier Transform), IFT (Inverse Fast Fourier Transform). 

These functions perform a (complex) fast fourier transform on either 1 or 2 
dimensional FLOATING-POINT arrays, obtained by: ARRAY(array,FLOAT,diml); or 
ARRAY(array,FL0AT,diml,dim2); for Id arrays diml must equal 2 n -l, and for 2d 
arrays diml=dim2=2 n -l (i.e. the array is square). (Recall that MACSYMA arrays 
are indexed from a origin so that there will be 2 n and (2 n )^ arrays elements in 
the above two cases.) 

The calling sequence is: 
FFT(reaf-array,imag-array) 

IFT (rea1-array,imag-array) 

The real and imaginary arrays must of course be the same size. The transforms 
are done in place so that real-array and imag-array will contain the real and 
imaginary parts of the transform. 

Other functions included in this file are: 



POLARTORECT<77?a£n/fi/cfe-array,p/>ase-array,) converts and magnitude phase 
arrays into real/imaginary form putting the real part in the magnitude array 
and the imaginary part into the phase array 



RECTTOPOLAR(rea/-array,/ma£-array> undoes POLARTORECT 
(the above 4 functions return a list of their arguments) 

[1 2. 1 5.3] Roots of Equations by Interpolation 

The file INTPOL FASL, created by Charles Karney, contains the function 



MACSYMA 12.15.3 Roots of Equations by interpolation 227 

INTERP0LATE<7unc,x,a,d; which finds the zero of func as x varies. The last two 
args give the range to look in. The function must have a different sign at 
each endpomt. If this condition is not met, the action of the of the function is 
governed by INTPOLERROR[TRUE]). If INTPOLERROR is TRUE then an error 

,°^^V^" WiSe the Va,ue of ,NTp OL€RROR is returned (thus for plotting 
INTPOLERROR might be set to 0.0). Otherwise (given that MACSYMA can 

m T a ™^ i h T e r- first ar S um( * nt in the specified range, and that it is continuous) 
INTERPOLATE is guaranteed to come up with the zero (or one of them if 
there is more than one zero). 

I?4™ C £ J , r ? Cy ° f ,NTERP0L ATE is governed by INTPOLABS[0.0] and 

nmrlSbS H£° ] Whlch mUst be non -negative floating point numbers. 
INTERPOLATE will stop when the first arg evaluates to something less than or 
equal to INTPOLABS or if successive approximants to the root differ by no 
more than INTPOLREL * <one of the approximants> The defaults values of 
INTPOLABS and INTPOLREL are 0.0 so INTERPOLATE gets as good an answer 
as is possible with the single precision arithmetic we have. The first arg may 
be an equation. The order of the last two args is irrelevant. Thus 

INTERP0LATE(SIN(X)=X/2,X,XPI,.l); 

is equivalent to 

INTERPOLATE(SIN(X)=X/2,X,.l,%PI); 

The method used is a binary search in the range specified by the last two 
args. When it thinks the function is close enough to being linear, it starts 
using linear interpolation. 

An alternative syntax has been added to interpolate, this replaces the 
first two arguments by a function name. The function MUST be TRANSLATEd 
or compiled function of one argument. No checking of the result is done, so 
make sure the function returns a floating point number. 

F(X):=(MODEDECLARE(X, FLOAT), SIN(X)-X/2.0); 

INTERPOLATE(SIN(X)-X/2,X,0.1,%PI) .tine- 60 msec 

INTERPOLATE(F(X),X,0.1,%PI); time* 68 msec 

TRANSLATE(F); 

INTERPOLATE(F(X),X,0.1,%PI); time- 26 msec 

INTERPOLATED, 0.1, %PI); time* 5 msec 
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[ 1 2. 1 5.4] Special Functions 



The file BESSEL FASL Contains rniitinoe far rnmni i*incr nnmoriral valnoc fr»r 

various special functions. If they are given non-numeric arguments they return 
themselves. 

Bessel Functions 

The following functions compute Bessel functions of integer order for real 
arguments. 



J OCX; returns the value of the zeroth order Bessel function at X 
J 1 (X) returns the value of the Bessel function of first order at X 



JN(X,N) returns the Afth order Bessel functioa In addition it sets up an array 
JARRAY of N+l elements, (numbered from to ABS(N» such that JARRAY[I] 
gives the value of the I'th order Bessel function with argument X. (If N < 
then JARRAY[I] gives the (-l)'th Bessel function). 

Modified Bessel Functions 

The following functions compute the Modified Bessel Functions I of integer 
orders for real arguments. 



\0(X) returns the value of the modified Bessel function of zeroth order. 
\l(X) returns the value of the modified Bessel function of first order. 

\N(X,N) works the same way as JN(X,N), except that the array is called IARRAY. 

Since the modified Bessel function blows up like EXP(ABS(X)) at infinity, they 
cannot be evaluated directly for ABS(X) > 83 (due to overflow). The following 
functions avoid this problem: 
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GOW returns IO<X)*EXP(-ABS(X)). 
Gl (X) returns ll(X)*EXP<-ABS<X)). 



GWKN) returns IN(X,N)*EXP(-ABS(X)). The array generated by GN is called 
GARRAY. 



Complex Bessel Function of positive fractional order 



BESSEUZ,A) returns the Bessel function J for complex Z and real A > 0.0 . Also 
an array BESSELARRAY is set up such that BESSELARRAY[I] = J[l+A- 
EIMTIER(A)](Z) 



AIRYW returns the Airy function Ai of real argument X. 

Plasma Dispersion Function, NZETA(Z). 

This function is related to the complex error function by 
NZETA(Z) = %I*SQRT(%PI)*EXP(-Z*2)*(1-ERF(-%I*Z)) 



NZETA^ returns the complex value of the Plasma Dispersion Function for 
complex Z. 



NZETARCZ; returns REALPART(NZETA(Z)). 

NZETAIfZ) returns IMAGPART(NZETA(Z)). 
Normal distribution function 



GMSS(MEAN,SD) returns a random floating point number from a normal 
distribution with mean MEAN and standard deviation SD 
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[ 1 2. 1 5.5] Polynomial Zeros 



REALZEROf poly ;any thing) is a program to isolate zeros of a polynomial based on 
the Collins-Loos differentiation algorithm. The 2nd argument,currently ignored, 
is reserved for some "epsilon" To access it, one must 

L0ADFILE(eb,lap,dsk,rjf)8 , BATCH(C0LLIN, H > ,, ,DSK I RJF)8, 

TRANSLATE(IS0LATE,RR)8. It seems to be slower than REALROOTS for a 
similar task (occasionally uses NROOTS, though it needn't). 
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13 The MACSYMA Editor 

13.1 Introduction 



The major features of the editor are jts concise commands (few alphabetic 
characters), its varied assortment of commands, concatenation of commands as in 
TECO (the PDP-10 file editor), mnemonics for command names (or^s you know 
them, R means "move in the Reverse direction" ; B means "move to the Bottom" ), 
and compatibility with TECO as to command names (in the case of C, D, F, G, I, J, 
K, L f R, and S). 



1 3.2 Entering the Editor 



At any time while the user is inputting a command line to MACSYMA, he may 
enter the input-stream editor by typing "altmode" or "escape", henceforth 
denoted by <S>. The editor is given the string of characters typed so far in the 
current input line. In the case of a detected syntax error, upon typing <8>* the 
entire previous command string will be given to the editor. Alternatively, 
<control>-Y also retrieves the previous command string (even if other characters 
have already been typed in the current C-line). Thus, the previous command line 
is readily available for editing without retyping it. 

When MACSYMA detects a syntax error in an input line, the error message 
sometimes displays the offending expression to help the user pinpoint the source 
of error. This is inconvenient if the expression is large, especially when the user 
has a slow terminal. Gradually this scheme is being replaced by a scheme that 
does not display the offending expression, but rather sets ERREXP to it, and 
prints out the error message followed by the message "ERREXP contains the 
offending expression". 

One may also request the editor to edit or modify a previously accepted input 
line by using the STRING function in MACSYMA. Typing STRING(Ci) will restore 
the expression labeled as Ci as the current input string. This enables the user to 
modify it by then immediately typing <S>. For a simpler method, see the MYV 
command below. 



1. <S> must be the first character typed on the next command line. Any other 
character (except "space") causes the edit buffer to be emptied. 
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All the commands to the editor reference a cursor (displayed as an 
underscore or back-arrow, depending on the console) which is displayed within or 
at either end of the string of characters currently being edited (called the "input 
string" from now on). The value of the variable CURSOR determines what 
character is used (see 10.7). 

The editor accepts a command string which must be terminated by <S><8>. A 
command string is any concatenation of one or more legal commands which will be 
processed in left-to-right order. Display of the input string occurs at the end of 
the processing of each command string. <8> is used to enter the editor, to exit 
from the editor (as <8><B>), and to terminate insert or search substrings. 
Otherwise, spurious <8>'s are ignored. Rubouts (the rubout or delete key on the 
console) may be used at any point prior to command termination to delete the last 
character typed in. ?? deletes the entire command. At any point prior to command 
termination, the user may type a <control>K, and the editor will reprint the 
characters of the command typed so far. 

Occasionally, one gets a syntax error because of omitting characters from the 
end of a command (especially right parentheses). By typing <8><S><8> 
immediately, as the first 3 characters of the next input line, the last command will 
be automatically reproduced on the current input line at which point one can 
supply the missing characters or rubout erroneous characters. For example: 

(Cl) (((X+l)*X+2)*X*3t 
(((X+1)«X + 2)«X*3 ******* 
SYNTAX ERROR 
PLEASE REPHRASE OR EOIT 

(Cl) <•> 

__(((X+l)*X+2)*X+3 

<*><$> 

(Cl) (((X+l)*X+2)*X+3 )*X44t 

(In the above line the user typed the 

characters after the 3) 



13.3 A Description of the Commands 



Some commands may be prefixed by an integer (represented below by V) 
which usually may be positive or negative; although it may be zero as well in the 
case of K, L, and W; and it must be non-negative in case of W. The default value 
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of n is +1. Except in the case of R, if n is positive the commands operate toward 
the right of the cursor, if n is negative they operate toward the left. I and S are 
two of the few commands which may be followed by other characters, namely the 
characters which constitute the insert or search strings. An error message will be 
printed if an illegal command substring is encountered or if any command substring 
fails. In case of such error, the processing of the current command string will be 
terminated at that point, with the offending command substring indicated. 

Command Mnemonic Action 



Commands which move the cursor 

nC Character moves the cursor past n characters. 



nR 



Reverse moves the cursor past n characters in the reverse 
direction (nR « -nC). 



J or T Jump to Top moves the cursor to the beginning of the input string. 

B or ZJ Bottom moves the cursor to the end of the input string. 

nL Line moves the cursor to the right of the nth carriage return 

(OL moves left); e.g., L moves to the next line. 

nSstring<S> moves the cursor to the right (left if n is negative) of 

the nth occurrence of "string" in the input string. 

nS Search repeats the last S command given. 

) or ] Move moves the cursor right from the current position over 

the next balanced pair of parentheses (or brackets). 

( or [ Move similar to ) or ] but moves left 

Commands which delete characters 

nD Delete deletes n characters, and saves them in the "save- 

register" (see the G command below). 
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nK Kill deletes all the characters through the nth carriage return 

(OK kills left), and saves them in the "save-register"; 
e.g., K deletes the remainder of this line. 

M) or M] Delete similar to ) or ] but deletes the characters moved over 

and saves them in the "save-register". 

M( or M[ Delete similar to M) or M] but moves left 

nFRstring<S> deletes the next n occurrences of string. (This command 

is a special case of the FR command below and can be 
used in this way only when it is the last argument in the 
command string). 



Commands which insert characters 

lstring<S> Insert inserts the characters "string" at the current cursor 

position. The cursor is positioned at the right of the 
inserted text. If no argument is given then the string of 
the last I command which had one is used. 

G Get inserts at the current cursor position the characters 

deleted by the last use of D, K, or M. Thus G may be 
used in combination with D or K to move characters from 
one place to another in the input string; or to recover 
from an accidental use of D or K. There is only one 
"save-register". 

nFRstringl<S>string2<8> replaces the next n occurrences of stringl by string2. If 

n is 1 it may be omitted. nFR given with no string 
arguments uses those from the last FR given which had 
them. 

MFRstringl<fi>string2<8> replaces all occurrences of stringl by string2. 

YVname<S> Yank value puts into the editing buffer, the value of the argument 

whose name is given, if a label or the name of a user 
variable, at the current cursor position leaving the 
cursor at the end of the inserted string. 

YFname<S> Yank function puts into the editing buffer the definition of 
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the user function whose name is given (as with YV). If 
the name is followed by a list of subscripts in brackets, 
then the named subscripted function is brought into the 
buffer. This command provides an alternative to 
DISPFUN and STRING (see 10.2). 



Note: If the YV or YF commands are prefixed by the letter M then the editor will 
clear the buffer before yanking, and also will leave the cursor at the head of the 
edit string when done. 



Commands which control display of results 

P Print simply reprints the input string. This is useful in case of 

console problems. 

nW Window controls the window size of the display, which is the 

maximum number of characters displayed on each side of 
the cursor. This is useful in case of slow consoles and 
large input strings. 0W will cause only the cursor to be 
displayed. Once set the window size remains at that 
setting until it is reset. VView restores the display to 
full view, which is the normal mode (affected only by W). 

Quit exits the editor without reprinting the just edited string. 



<8><S> will exit from the editor and is also the command string terminator. 
Two examples of legal command strings are 4C3DIF00<8><8> and 
-2SBAR<8>3R<S><8>. The first moves right over four characters, deletes the 
next three characters, and inserts F00. The second searches from the current 
pointer position to the beginning of the text for the second occurrence of BAR 
then moves left over three characters. 

Example 
(Cl) X:l» 
(C2) NATRIX([A,4],[-l,A/2]); 

(02) NATRIX([A, 4], [- 1, 1/2 A]) 

(C3)<»> 
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_NATRIX([A,4],[-l,A/2]) 

DIM<8><$> 

M_ATRIX([A,4].[-l,A/2]) 

]2GD<3XS> 

MATRJX([A,4],[_l,A/2]) 

<s><8> (In the line below the user typed the ;) 

(C3) MATRIX([A,4],[l,A/2]); 

[A 4 ] 
(D3) [ ] 

[1 1/2 A ] 

(C4) CHARPOLY(X.X); 

(04) (A - 1) (1/2 A - 1) - 4 

(C5)<5> 

_CHARPOLY(%,X) 

S%<S>-DID3<t>CI'<tXt> 

CHARP0LY(D3,'_X) 

<txt> (in the line below the user typed the ;) 

<C5) CHARP0LY(D3,'X); 

(D5) (A - X) (1/2 A - X) - 4 
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14 Batch Functions 

14.1 Introduction 



The Batch set of functions in MACSYMA, namely BATCH, DEMO, and BATCON 
(mnemonic for BATch CONtinue), provide a facility for executing command lines 
stored on a disk file rather than in the usual on-line mode. This facility has 
several uses, namely to provide a reservoir for working command lines, for giving 
error-free demonstrations, or helping in organizing one's thinking in complex 
problem-solving situations where modifications may be done via the PDP-10 TECO 
file editor. 

A batch file consists of a set of MACSYMA command lines, each with its 
terminating ; or S, which may be further separated by spaces, carriage-returns, 
form-feeds, and the like. The BATCH and DEMO functions have both a simple and 
more complicated format, which are described below. 



14.2 Thie Simple Format 



BATCH(7//ename2, filename2, DSK, directory) 

(The same function format holds for DEMO as well.) The arguments to BATCH 
(or DEMO) in this format specify the file which is to be batched. Here, each file is 
specified by two filenames of at most six characters each, the device the file is 
on ( which is normally DSK), and the user file directory. E.g. 
DEMO(TAYLOR,DEMO,DSK,DEMO) calls for "demonstrating" (see below) the file 
TAYLOR DEMO on the DEMO disk directory. Latter arguments to the BATCH or 
DEMO functions may always be omitted if they are known from previous file- 
manipulating functions. 

The BATCH function calls for reading in the command lines from the file one at 
a time, echoing them on the user console, and executing them in turn. Control is 
returned to the user console only when serious errors occur or when the end of 
the file is met. Of course, the user may quit out of the file-processing by typing 
control-G at any point (see 4) . 

DEMO differs from BATCH only in that it pauses after the execution of each 
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command line, waiting for the user to type a space which tells it to go on. If the 
user types any other character, file-processing will then terminate, giving control 
over to the user console. (The user may actually continue processing from the 
file at any time - see the BATCON function below.) 



1 4.3 The More Complicated Format 

BATCHf/fti/, fn2, DSK, directory], <delay-$witch>, <index-specification>) 

The arguments to BATCH or DEMO in this mode are as follows: 

The first argument is the file specification (as above), enclosed in brackets. 

The second argument, the delay-switch, may be answered by ON or OFF (the 
default if it is omitted). This switch has to do with the temporary inability of LISP, 
the system underlying MACSYMA, to have more than one input file open at a time. 
If in the course of batching in a file of command lines, execution of a function 
forces a second file to be input, this would ordinarily cause an error. However, 
setting the delay-switch to ON causes the entire batch file to be read in before 
execution of it begins, thus preventing the error. The default for the delay- 
switch is OFF, as the circumstance described above is not frequent, it takes some 
time to read in a batch file, and one may always continue batching via the 
BATCON function. As soon as the inability of LISP is removed, this switch will no 
longer be needed. 

The index-specification is given by one or two arguments, the possibilities 
being: (In the following, m and n are positive integers.) 

(i) m. This indicates that processing is to begin with the mth command line in 
the file. Thus, the default for the index-specification is 1. 

(ii) m t n. This indicates that only the mth command line through the nth 
command line are to be processed. 

(iii) a variable (say FOO). F00 must be non-numeric and neither TRUE nor 
FALSE. This causes file-processing to begin at F00&& (see 14.5) and 
continue until the end of the file. This makes it unnecessary to count command 
lines as required by (i) above. 

(iv) variable (say FOO), continue-flag. The continue-flag is either ON (the 
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default, and unnecessary) or OFF. If OFF, this enables one to separate a batch file 
into subfiles by prefixing a command line in the file with FOO&&. By using FOO as 
the index-specification, one may execute only that subfile which begins with FOO 
and ends with some other variable&&, or the end of file. If the continue-flag is 
ON, this causes mode (iv) to operate as (iii) above. 

One can see that BATCH(TAYLOR,DEMO,DSK,DEMO) and 

BATCH([TAYLOR,DEMO,DSK,DEMO], OFF, 1) are equivalent. 

14.4 The BATCON Function 



The BATCON function is used to continue or change the last BATCH or DEMO 
function, without it being necessary to mention again BATCH or DEMO, the file 
specification, or the setting of the delay-switch. Of course, if one wishes to 
change any of these, a new call to BATCH or DEMO is required. 

The possible arguments to BATCON are as follows: 

(j) a number 

(ii) number 1, number2 

(iii) a variable 

(iv) variable, continue-flag 

They are all as in 8.3. The numeric arguments may involve the variable 
BATCOUNTfO] which is set to the number of the last expression BATCHed in from 
the file. Thus BATCON(BATCOUNT-l) will resume BATCHing from the expression 
before the last BATCHed in from before. One other mode is possible: 

(v) skip-flag. The skip-flag is useful if an error has occurred while batching, 
or if the user wishes to interject command lines from the console while in DEMO- 
mode and then to continue processing from the file. The skip-flag may be either 
TRUE or FALSE. If FALSE, this indicates that processing is to continue with the 
last command line attempted (supposedly edited, in case of error); if TRUE, this 
indicates that processing is to continue with the next (untried) command line in the 
file. 



240 MACSYMA 

14.5 Miscellany 



( 1 ) Comments may be added to batch files at any point, and will, of course, be 
treated as such when batching in the file. A comment is any string beginning with 
/* and ending with */ as in PL/I. 

(2) Any command line in a batch file may begin with variable&&. This labels 
that command line so that the file can be partitioned into subfiles. If not in a 
subfile mode, this prefix will be treated as a comment. 

(3) When using the batch functions, it is inconvenient to keep track of which 
Di label MACSYMA will assign to a computation; yet later command lines often 
need to refer to an earlier computation. One way to get around this, of course, is 
for the user to explicitly label some of his command lines. A function %TH is also 
provided, such that # /.TH(i), where i is positive, refers to the result of the \th 
previous command line. E.g., %TH(1) and the variable % both refer to the same 
computation. 

(4) When BATCHing in several files it is possible for one file to 
unintentionally cause an error to occur in a subsequent one by duplication of 
names or settings of options. If the variable BATCHKILL[FALSE] is TRUE 
however, then the effect of all previous BATCH files is nullified because a 
KILL(ALL) and a RESETO will be done automatically when the next one is read in. 
If BATCHKILL is bound to any other atom then a KILL(BATCHKILL) will be done. 
(The default value of BATCHKILL is FALSE meaning to do nothing.) 

(5) While BATCHing in a file which takes a lot of time to process the user 
may leave his terminal unattended. If an error occurs he may want some special 
action to be taken automatically. By setting the option ERRORFUN to the name of 
a function of no arguments one can have that function executed when any error 
occurs. Useful functions are QUIT and LOGOUT. However in the case of LOGOUT 
the user should also set the switch TTYOFF to TRUE to prevent his job from 
hanging up in the case it tries to output to the terminal (see 4). In addition if a file 
has been opened for writing, then a command to close it should be executed 
before the LOGOUT. Also, the user may wish to set DYNAMALLOC[FALSE] to 
TRUE (see 16) so that his job will not hang if additional storage space is 
needed 

If the user is executing a function of his own and would like to signal an error 
he can use the functions ERROR and ERRCATCH (see 10.6). 
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(6) If the user does not have a directory of his own then he can use the one 
called USERS to store his files. He should identify them as his in some fashion 
such as using his login name for the first file names. 

(7) The DEMO file directory contains many demonstration files which may be 
helpful to the user in learning to use MACSYMA. 
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15 Secondary Storage Functions 

15.1 Introduction 



There are two different reasons for wanting to use secondary storage while 
running a MACSYMA. Sometimes the user's intermediate expressions are large, 
and it is impossible to complete the job if all the intermediate expressions are 
kept in main memory. In this case the user would like to have his intermediate 
expressions written automatically onto the disk, in order to free main memory. On 
the other hand, some users would like to save some expressions onto the disk so 
that they can be read back into a future MACSYMA at a later time. In this case 
the user would like to specify certain expressions to be stored and to name the 
disk file where they are to be stored MACSYMA offers the user two secondary 
storage schemes. The user may ask to have his expressions automatically filed 
away onto the disk, or he may, by means of the SAVE and STORE functions, 
exercise explicit control over the storage of expressions. These latter functions 
give the user more power and flexibility at the expense of a greater effort. It is 
expected that the user whose only concern is to run a big job which would not 
run without using secondary storage will use the automatic storage scheme, while 
the user who wishes to save expressions for use in later MACSYMAs will use the 
SAVE and STORE functions. 



1 5.2 Automatic Storage of Expressions 



A - How to use it 



To activate the automatic storage scheme the user merely sets the 
MACSYMA option DSKUSE[FALSE] to TRUE. From this point on labelled 
expressions will be written out periodically onto the disk. (A labelled expression 
is one which is referred to by a line label, e.g. D4, C7, El 2.) Once an expression 
is written onto the disk it will no longer reside in main memory and most of the 
main memory storage taken up by it will be released. When the user attempts to 
reference an expression which has been stored onto the disk, MACSYMA will 
retrieve the correct value from the disk file. In this scheme expressions are 
copied periodically onto the disk whenever there are enough to write out (see 
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FILESIZE). An alternative heuristic to use in order to free some storage is to 
write out all labelled expressions, values, functions, and arrays whenever the 
garbage collector finds that space is getting low. This is the purpose of the 
DSKGC function (see 10). 

If the user is dealing with large expressions then his storage limit may be 
exceeded before FILESIZE expressions have been generated. In this case the 
DSKGC method should be used. If this situation does not occur and if the user 
prefers to have some control over how many expressions are saved in each file 
then the other scheme should be used. 



B - Cleaning up the disk 



The automatic storage scheme will in general cause several disk files to be 
created, which are of no further value after the user has finished running his 
current MACSYMA. There is a function called REMFILE, which will delete all the 
files created by the automatic storage scheme. Thus if the user does not want 
these files to stay around, he should execute REMFILEO before leaving MACSYMA. 
REMFILt will only delete files created in the same MACSYMA to which the 
REMFILE function is given. In order to delete files created in previous uses of 
MACSYMA it is necessary to use the DELFILE function (see 10). 



C - Options 



The user may specify how often files are written, how large they are, what 
they will be named, and what gets stored in them, or he may accept the default 
values for all these. The following MACSYMA options are relevant. 

FILENAME - The value of this variable is the first name of the files which are 
generated by the automatic disk storage scheme. The default value is the first 
three characters of the user's login name concatenated with a three-digit random 
number (e.g. ECR864) 

STORENUM - The value of this variable, an integer, is the second name of the 
last file written. Each time a file is written, this value is first increased by 1, so 
it must always be an integer. It is initially set to 0. 

FILESIZE - The value of this variable is the number of expressions written 
into each file. The default value is 16. 
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DEVICE - The value of this variable is the default device. It is initialized to 
DSK. 

......._ -I-! i _t 1L!. I.LI- :_ IL- J^i U ^--. — ^ 14 :*» iniliAlilA/4 ♦<-» 

UIMAMt - I ne vaiue or mis vanaoie is me ueiauu uridine, u. ip niiHqntcw w 
the user's login name, if he has a disk directory, and to USERS otherwise. UNAME 
determines to what directory disk files will be written. 

DIREC - may be used as an alias for UNAME. 

DSKALL - If TRUE will cause values, functions, arrays, and rules to be written 
periodically onto the disk in addition to labelled expressions. TRUE is the default 
value whereas if DSKALL is FALSE then only labelled expresions will be written. 

1 5.3 Explicit Storage of Expressions 



1 5.3. 1 Use of the storage functions 

The functions SAVE, STORE, and FASSAVE allow the user to explicitly state 
that certain expressions should be written onto the disk. These functions also 
allow him to specify the file into which these expressions should be written. 
They allow the user to store away arrays, function definitions, rules, and any 
other type of information. The main purpose of these functions is to allow the 
user to save expressions onto the disk so that they can be read into future 
MACSYMAs. 

SAVE and STORE are identical in all respects but one. When an expression is 
STOREd it is both written onto the disk and removed from main memory. (When 
the expression is referenced, of course, the correct value is retrieved from the 
disk.) When an expression is SAVEd, it is written onto the disk but not removed 
from main memory. The only difference between these two functions is their 
effect on main memory storage. 

FASSAVE is similar to SAVE but produces a FASL file in which the sharing of 
subexpressions which are shared in core is preserved in the file created, hence, 
expressions which have common subexpressions will consume less space when 
loaded back from a file created by FASSAVE rather than by SAVE. The user 
should note that FASSAVE files are not as flexible as SAVE files since the 
RESTORE function (see below) cannot be applied to them. Also if the user's 
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MACSYMA Is already near maximal allocation, FASSAVE , which uses a 

o°Awn de r?, ble am ° Unt ° f Space and time jn dojn * its i° b » ma y n ot work, whereas 
SAVE still might. 

SAVE, STORE, FASSAVE take any number of arguments. If the first argument 
is a list it is assumed to be the file specification (e.g. [fnl, fn2, DSK, directory]) 
In accordance with the standard options for file specifications, the latter 
arguments may be omitted from the list and the defaults will be assumed. If the 
first argument is not a list, the expressions will be written into a file with the 
default filename. The value of the MACSYMA variable FILENAME is the default 
first filename, and the value of the MACSYMA variable FILENUM is the default 
second filename. The value of FILENUM is increased by 1 each time a file is 
written, so its value must always be an integer. FILENUM is initially 0. The value 
of DEV is the default device, and the value of UNAME is the default username. 

All arguments to SAVE or STORE, except possibly the first, must be one of 
the following: 

(i) The name of an "information list" (see 8.1). SAVE(VALUES) will not cause 
M A C SYMA options (e.g. SHOWTIME, RATPRINT, etc.) to be saved. Also ALIASES 
will be automatically saved with every use of the SAVE function if they exist. 

(2) ALL When this atom is an argument every quantity associated with any 
information list is written. 

(3) [m,n] when this list is given as an argument, every label whose line 
number lies between m and n inclusive gets written. 

(4) When any other atom is an argument, it must be either an array, a 
function, or have a value. It gets written onto the disk. 

(5) A=B The effect is similar to the case where the argument is just B, i.e. B 
gets written onto the disk. The only difference shows up if the file is read into 
some future MACSYMA. In that case, the expression which is referred to as "B" 
in the present MACSYMA will be referred to as H A M in the future MACSYMA. For 
example, suppose the user wishes to save some expression, say D7, for use in a 
future MACSYMA. He can execute ST0RE([F00, BAR], YESTERDAYSD7 = D7). D7 
is now stored onto the disk. When he comes back the following day and load in a 
fresh MACSYMA he merely executes L0ADFILE(F00, BAR, DSK, ECR) and the 
variable YESTERDAYSD7 will take on the value which D7 had yesterday. This 
renaming however has no effect on the present MACSYMA, where D7 must still be 
referred to as "07" Note that if a SAVEd or STOREd file contains labelled 
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expressions they may conflict with expressions having the same label in the 
MACSYMA into which the file is loaded. For example if D9 is In a file which is 
loaded into a MACSYMA then it would replace the 09 which was already in the 
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when the new D9 was generated. To avoid this difficulty the user should give 
labelled expressions a name as described in (4) above. He could also set 
LINENUM in the new MACSYMA or save it from the old one so that line numbers 
wouldn't conflict. 

The user should note that each use of the SAVE or STORE function will cause 
exactly one file to be written, regardless of the number of arguments the function 
is given. 

REMFILE(TRUE) will perform REMFILEO (see 15.2 - B) and in addition will 
delete files created by SAVE or STORE which haven't been assigned names 
explicitly by the user. 

Certain MACSYMA variables (i.e. LINENUM, FILESIZE, etc.) are used to 
communicate to the MACSYMA system that certain options are in effect, or to tell 
the system to use certain values. These variables should not be STOREd (though 
they may be SAVEd), since the system programs will not be able to correctly 
retrieve their values from the disk. In general, one should not attempt to STORE 
variables whose purpose is to provide information to the system (i.e. MACSYMA 
options). 



1 5.3.2 Retrieval of expressions stored on disk 



1 - In the MACSYMA you are using 



Expressions which are written onto the disk using the SAVE function also 
reside in main memory, so the notion of retrieving them from the disk in the 
present MACSYMA is not applicable. Expressions written onto the disk using 
STORE, however, no longer reside in main memory. When such expressions are 
referenced the system will always retrieve the correct value from the disk. 
When a STOREd array is referenced, the array will be brought back to main 
memory. Functions and values will be read from the disk correctly, but will not be 
returned to main memory. If the user wants to bring an expression back to main 
memory he may use the function UNSTORE. This function takes any number of 
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arguments. Each argument must be an atomic variable, and if this atomic variable 
refers to an expression which is stored onto the disk, the expression is returned 
to main memory. Of course, when an expression is UNSTOREd, either by the user 
or by the system (as happens when STOREd arrays are accessed), a copy of the 
expression still remains on the disk in the assigned file. 

2 - In future MACSYMAs 

■ Fi !! S C , r ^ d by SAVE and ST0RE can be ,oaded in *o future MACSYMAs 
us.ng the LOADFILE function. This will set up in main memory all those 
expressions which were written into the file. Some of the expressions will have 
different names than they had in the MACSYMA where they were created, if the 
renaming option (i.e. arguments of the form A=B) of the STORE or SAVE function 
was used. Also, unless the FASSAVE scheme was used, expressions will generally 
take up more space than they did in the MACSYMA where they were created, as 
sharing among common subexpressions will be lost. 

! 5.4 Saving a MACSYMA Overnight 

Often a user in the middle of his work would like to save everything onto the 
disk so he can go home and resume work tomorrow. When the user decides to 

^ V w,-,r the State 0f hls MAC SYMA, he should execute for example: 
SA VE([f n 1 ,f n2,DSK,directory],ALL) 

This wifl write all his lines, arrays, functions, values, rules, and aliases (if he 
has created any), and the current value of LINENUM into a single disk file named 
fnl fn2 (where these may be any names given by the user). Of course, the user 
should choose names for his files which are unique. If he does not have his own 
directory then he should use the USERS directory and his login name for the first 
file name. If the automatic storage scheme was in effect he should now execute 
REMFILEO; to delete useless files from the disk. When the user comes back the 
next day he should load a fresh MACSYMA and execute one of the following two 
functions: 

L0ADFILE( fnl, fn2 f DSK, directory) ; 
or restore* fnl, fn2, DSK, directory); 
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The first command will cause all expressions to be loaded into the present 
MACSYMA. Whereas all the expressions may have fit into the MACSYMA in which 
they were generated, they may not fit into a new MACSYMA, because common 
subexpressions originally shared will not be shared in a new MACSYMA. However 
if the OPTIMIZE function is used (see 6.2.3), then some sharing of common 
subexpressions may be obtained. The RESTORE function does not cause the 
expressions to be loaded into main memory but does permit them to be accessed 
when needed. (This is as though STORE had been used on the information.) Thus 
it should be used if it is not desired to bring all the expressions into main memory 
at the same time. 
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16 Storage Management 

In the LISP system in which MACSYMA resides, the space requirements of the 
user's programs and data may be increased during the execution of the programs. 
This is in contrast to static storage allocation systems in which the storage is 
completely allocated before the programs are executed and consequently the 
storage requirements must be completely known before execution time and cannot 
be changed during program execution. If they exceed the capacity of the memory 
space that has been allocated for them, the programs will not be allowed to run. 

With our LISP system, a certain amount of space is initially allocated, the 
programs are started running, and the amount of space utilized changes during 
execution. If at some point the limit of available space is exceeded, program 
execution will be terminated. 

This LISP divides up the available memory spaces into several portions on the 
basis of what kind of data they will contain. 

BPS - (binary program space) for compiled functions and arrays. 

FIXNUM - for integers which fit into one machine word. 

FLONUM - for floating point numbers. 

BIGNUM - the first word of numbers bigger than one machine word. 

SYMBOL - for atomic symbols. 

ARRAY - for array indicators. 

LIST - for anything else not in the other spaces, e.g. uncompiled functions, 
symbolic expressions, etc. 

PDL - for several kinds of pushdown lists. 



When a MACSYMA is started up, each space is initially allocated some fixed 
amount. These spaces will grow as the user interacts with MACSYMA, each 
particular space growing as the user causes more objects to be created which 
reside in that space. For example, executing a command line which causes an out- 
of-core file to be loaded mainly increases BPS and LIST space. Also new labelled 
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expressions are created every time a command line is executed and these occupy 
LIST space. Push down lists are used to store variables, return addresses, and 
other information related to the function calling mechanism. 

When a space (except for BPS and the PDLs) is used up, a process is 
initiated called "garbage collection" which attempts to free up storage so it can be 
reused rather than trying to increase the size of the spaces. In very simple terms, 
it marks every word in a particular storage space which is still being utilized and 
then links up the unmarked words (termed "garbage") on a chain to be used to 
store subsequently created data. If this chain is not of a certain assigned minimal 
size, a special allocation routine is invoked. At this point several possibilities can 
occur, among which is the possiblity of increasing the size of the spaces. Before 
these are described however, there is something to be mentioned which the user 
should take note of. The initial allocations (later to be referred to as "level 
allocations") are quite reasonable. Many problems run quite well using these 
allocations. If the user's problem does not run due to running out of storage, most 
often this is due to one of the following circumstances and not to the insufficiency 
of the allocations: 

(1) The user has organized his problem poorly, thereby either not solving 
the problem he intended to solve, biting off too much in too short a time, or 
creating intermediate expression swell of perhaps incredible proportions. He 
should get a feel for the size of all of his expressions and the behavior of 
MACSYMA's functions on them. 

(2) The user is retaining expressions in core that are useless to him. 
Since MACSYMA maintains a complete history of the user's session, it does 
not release the storage occupied by the user's data unless explicitly 
instructed to do so. This can be accomplished in several ways. One way is by 
using the functions KILL, REMVALUE, REMFUNCTION, and REMARRAY (see 
10.3) which unbind an item from the expression it represents thus freeing up 
the storage occupied by the expression to be reclaimed on the next garbage 
collection. It is recommended that the user give a name to all labelled 
expressions which he wishes to keep around for a time, and then periodically 
do a KILL(LABELS). He should also KILL functions and arrays which he no 
longer needs. Killing a name will not accomplish much unless the labelled 
expression (D line) at which the assignment was done is also KILLed because 
the two symbols are holding onto the same expresson. 

If the above approach is unacceptable because the (intermediate or final) 
expressions which the user needs occupy a lot of storage, he can store them 
on the disk (kill the corresponding label if any) and have them retrieved when 
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needed. This can be accomplished in the following two ways (see Chapter 
15). 

The STORE function can be used to explicitly transfer expressions from 
main memory to disk. These will be brought back into main memory each time 
they are referenced. Since the process of retrieving an expression from a 
large file may be rather time consuming, the user can use the UNSTORE 
function to bring an expression back to main memory and keep it there 
However, in general an UNSTOREd expression will occupy more space then it 
originally did because several copies of common subexpressions will be 
created These were originally represented by pointers to a single copy. 

Another way to transfer expressions to the disk is by using the automatic 
storage mechanism. This will cause expressions to be STOREd automatically 
in an effort to conserve space. As with the explicit use of the STORE 
function, the expressions will be retrieved by MACSYMA when they are 
referenced. There are two heuristics which MACSYMA uses to decide when 
to store expressions. One is to STORE all values, functions, arrays, and 
labelled expressions whenever available space becomes low. This is the 
purpose of the DSKGC function. The other heuristic is to periodically STORE a 
fixed number of labelled expressions whenever that many get created above 
a minimum number which are to be kept around. The user can utilize this 
option by setting the switch DSKUSE to TRUE. In addition if DSKALL is TRUE, 
then all values, functions, and arrays will be written at this time as well. 

(3) A recursive infinite loop has occurred because of a bug in either the 
user's code or in MACSYMA's code. Such a loop would cause storage spaces 
to grow indefinitely if possible. It may be difficult for the user to recognize 
that this situation has occurred, as opposed to a real need for more space, 
yet such a situation can cause havoc to any dynamic allocation scheme. By 
typing a control-D the user will be informed whenever a garbage collection 
occurs and a printout such as the following will occur: 



GC DUE TO ... SPACE 

2729[33%] LIST, 1935[94%J FIXNUM, 511[99%] FLONUM, 

509[99%] BIGNUM, 629[15%] SYMBOL, 

480[ 93%] ARRAY WORDS FREE 



The numbers before the name of each space give the number of words of 
that space which are available. The percentages refer to the ratio of the 
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available amount of space compared to the total amount (used plus unused). 
This may be of some help in determining whether the user's computation is 
doing what he expected. Typing a control-C will turn off this g.c. printout. 

If the user feels that he is not in one of the above situations and that there is 
a real need for more space, he can avail himself of the following scheme: 

When a space, e.g. LIST is exhausted, MACSYMA will print: 

You have run out of LIST space 

Do you want more? 

Type ALL; NONE; a level -no.; or the name of a space; 



At this point the user can type a control-A and enter a (MACSYMA-BREAK). 
He can then follow any of the procedures mentioned in (2) above. After getting 
out of the break by typing EXIT; he can then type OK; which indicates that the 
user believes he has freed up enough space thus making reallocation unnecessary. 
If he is wrong, he will get the above message again. He can also reply with the 
name of a space, i.e. one of FIXNUM, FLONUM, BIGNUM, SYMBOL, or ARRAY which 
will cause the size of that space to be expanded. If he replies with LIST or ALL 
then not only will list space be increased, but so will every other space. This is 
because if he needs more list space, then he probably needs more of the other 
spaces as well. Replying LIST also increments the "allocation level" by one. 
There are 5 equi-spaced levels of allocation, ranging from the initial level to 
level 4. The user can also boost his MACSYMA up to that particular level of 
allocation immediately by replying with that level number. 

At level 4 the maximal allocation possible on the computer is just about 
exhausted so that there is no higher level. Also, the amount of core space 
devoted to the allocatible storage spaces is obviously inversely proportional to 
the number and size of out-of-core files which are loaded in. If many out-of-core 
files are loaded in, allocation level 4 will not even be attainable. The user may 
wish for this reason alone to continue now and then with a fresh MACSYMA. If 
the user's computation exceeds this level of storage it will error out with the 
message "...STORAGE CAPACITY EXCEEDED". Since the size of the spaces can't be 
decreased, it is important not to increase them unless it is necessary. 

If the user knows initially that his problem will require much space, the 
function ALLOC is provided. ALLOC takes any number of arguments which are the 
same as the replies to the "run out of space" question above. It increases 
allocations accordingly. 
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Lastly, if he is running a MACSYMA disowned, or for other reasons wishes 
storage space to be increased automatically as needed without having any 
questions asked, the user may set the switch DYNAMALLOC [FALSE] to TRUE 
which will allocate additional space whenever necessary. 

Like the other spaces BPS and the PDLs cannot be decreased. BPS will 
continue to grow untiJ the MACSYMA runs out of address space so caution should 
be exercised in causing out-of-core files to be loaded. For example, once the 
integration file is loaded into the user's MACSYMA it is there to stay even if he 
no longer uses it. The allocation of the PDLs is sufficiently large, so that if they 
are ever caused to overflow it is probably due to a recursive infinite loop in the 
user's programs. 
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1 7 Simple Plotting Functions 

The MACSYMA functions PI HT PAPARJPI HT HPAPU an/4 uiiitigdadu ^h- — 
character plots of specified functions and sets of data points. (They can also be 
used to produce output files for plotting on the Calcomp plotter or XGP attached 
to the POP- 10 used by the Artificial Intelligence Group). The format of these 
functions and the variables used by the corresponding routines are described 
below: 

Variables 

LINEL - width of graphing area in terms of number of characters. 

PLOTHEIGHT - height of graph in terms of number of characters. 

XAXIS[FALSE] - if set to TRUE will cause the Y=0 axis to be displayed. 

YAXIS[FALSE] - if set to TRUE will cause the X*=0 axis to be displayed 

Formats for PLOT and PARAMPLOT 



PLOT(F(x), x, low, high) - plots the expression F(x) over the domain low < x < 
high. 



PLOKF(x), x, low, high, INTEGER) - as above, but plots F(x) only for integer 
values of x. 



PLOT(F(x), x, [xl, x2, x3, ..., xn]) - plots the function F(x) for the values 
xl,x2,x3,...,xn. 

The first argument to PLOT may also be a list of functions rather than just a 
single function. This permits several functions to be plotted on the same set of 
axes. Three optional final arguments may also be given. They are: (1) an X axis 
label (quoted string or name), (2) a Y axis label, and (3) a list of plotting 
characters used for the given function(s) enclosed in "s. (Note also that if a 
special symbol such as ; , S , etc. is used it must be preceded by a \.) An * will 
be used to plot any functions which are not given a particular plotting character. 
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PARfliMPL0T(fl(t),f2(t),t,low,high) plots the plane curve f(t) = ( fl(t) , f2(t) ) with 
parameter t. The syntax is basically like that of plot. For example, 

PARAMPLOT(COS(T),SIN(T),T,0,2*%PI) 

plots a circle, Also several curves may be presented at the same time by using 
the following syntax 



PARAMPLOTtfW;, gl(t), ... hl(t)l [f2(t), g2(t), ..., h2(t)] t t, low, high, [list of 
plotting characters]) - plots the plane curves f<t) = (f l,f2), g(t) = 
(gl,g2),...,h(t) = (hl,h2) using the specified plotting characters or the default 
V\ For example, 

PARAMPLOT([COS(T),COS(T)+73,[SIN(T),SIN(T)], 
T,0,2*XPI, ["§"]) 

plots two circles. 

The user may wish to TRANSLATE or COMPFILE (see 10.8) the functions to 
be plotted as they might be evaluated many times. 

Formats for GRAPH and MULTIGRAPH: 



GRAPHf/xi, x2, x3, ..., xn] [yl, y2, y3, ..., yn]) - Graphs the two sets of data 
points. 



GRAPHtf/xi, yl], [x2, y2], ..., [xn, yn]]) - Graphs the points specified by the list 
of coordinate pairs. 



GRAPHfxsef, [ysetl, y$et2,..., ysetn],optional-arg$) - allows graphing of one x- 
domain with several y-rangesj e.g. GRAPH([0 I 11[[0,11[1,2]1["&"]). 



MULTIGRAPHf/" [xset 1, ysetl], ..., [xsetn, ysetn] ], optional -args) - allows the user 
to produce a scatter-graph involving several x-domains each with a single y- 
rangej e.g. MULTIGRAPH([ [[0,1],[0,1]], [[3,4}[1,2]] ],[ M &"]). 

The three optional final arguments mentioned above under PLOT may also be 
used with GRAPH and MULTIGRAPH. 
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The plot produced by the above functions is a character plot on a coordinate 
system defined by axes along the minimum x and y values of the plot. The x and y 
coordinates are independently scaled to optimally use the specified graphing area. 
Note that this may distort the shape of the graph e.g., a circle could become an 
ellipse. The origin of the graph (left-hand corner) is given on the graph by the 
values of XORG and YORG; the computed increments (= one character) are given 
by the values of XDELTA and YDELTA and the maximum X and Y values are given 
by XMAX and YMAX. The axes are labeled with the number sequence 
0,2,4,6,8,0,2,4,... as an aid in counting the number of increments from the origin. 

When a graph is completed, the user must type a single character <on non- 
printing consoles), such as space or carriage return, to return control to 
MACSYMA. 

Examples 

(CI) XAXIS:YAXIS:TRUEt 

(C2) PLOT([l/<X~2+l),X*2-l],X,-2,2,[»]); 
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(C2) POLARPLOT(RHO,NUMBREV):rBLOCK([THETA, LIMIT, X, Y, P, NUMER, 
RATPRINT], NUMERrTRUE, RATPRINT: FALSE, THETA:0.0, X:Y:[], 
LIMIT :72*NUMBREV, FOR 1:1 THRU LIMIT DO 

I r;Knu\ incut;, A :tUNd I r*t05l intlA/,AJ, 

Y:CONS(P*SIN(THETA),Y), THETA:THETA*XPI/36.0), 
GRAPH(X,Y,X,Y))f 

(C3) XAXIS:YAXIS:FALSEt 

(C4) F(T):=4-COS(8.0/3.0*T)t 
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(C5) P0LARPL0T(F,3)t 
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18 Complex Plotting and Graphics — PL0T2 

18.1 Introduction 



This is a description of the functions contained in the following 6 files: 
APL0T2 > ARC CFFK, TEKPLT > ARC CFFK, PL0T3D > ARC CFFK 
WORLD > ARC CFFK, PRINT > ARC CFFK, IFFUN > ARC CFFK. 
They will be loaded up as needed when most of the functions below are used. 
However to get the "complete" PL0T2 environment, 

L0ADFILE(PL0T2,LISP,DSK,SHARE) is recommended This loads in complete 
AUTOLOAD properties for the functions described below. The effect of loading 
this file will be to cause the PL0T2 package to be automatically loaded when you 
need it. If you use PL0T2 regularly, you should consider including PL0T2 LISP DSK 
SHARE in your MACSYM (INIT) file; it will take up neglegible room in your 
MACSYM. 

The capabilities of the routines described here include plotting of several 
curves on a single graph, plotting several graphs in different positions on the 
screen, saving plots, replotting plots with different scales without having to 
recompute any points, plotting of 3 dimensional surfaces, plotting of user defined 
dashed lines and symbols. 

The devices supported are: the Tektronix 4Q10 and 4013, the Imlac PDS 1 
and PDS 4 (using ARDS graphics conventions), the XGP and the Gould line-printer 
(at MIT) and printing and display consoles in a "preview" mode. 



18.2 Two-Dimensional Plotting 



PLOT2(y-expr$,variabte,var-range,optional$-arg$) plots y-exprs on the y axis as 
variable (the x axis) takes on values specified by var-range. 
y-exprs can take one of two forms: 

i) expr plots a curve of expr against variable 

ii) [exprl t expr2 t .. % expri % .. t exprri] plots n curves of expri 
against variable, expri gets evaluated in the context 
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FLOW(EV(expri t variable=value gotten from var-range, 
NUMER)). It is an error if this doesn't result in a floating point 
number. 

var-range can have the following forms: 

i) low,high, where low and high evaluate to numbers, low may 
be either greater or less than high, variable will take on 
CALCOMPNUM values equally spaced between low and high. 

Note that the first argument will be evaluated at tow 
first e.g. PL0T2(i/X,X,-l,-3); calculates l/(-1.0) before 
l/(-3.0). This will only make a difference if the 
computation of the first arg changes a variable which 
changes the value returned by subsequent computation. 
Whether or not low < high, m\r)(low t high) will be on the left 
of the plot. 

ii) low,high,\mEGER. As in i), except variable will take on ail 
integer values between low and high inclusive. 

iii) [vafl t val2, ... , vain] . variable takes the values specified by 
the list 

iv) arrayname where array name is the name of a declared 
floating-point one-dimensional array (i.e. declared by 
ARRAY(arra>v?aroe,FLOAT, max-index);). variable takes the 
values from arrayname[0] thru arrayname\max-index~\ (max- 
index is the maximum index of arrayname 

optional-args can be any of the following: 

i) X-Label f Y-Label or Title descriptor 

ii) Line type descriptor 

iii) FIRST, SAME and LAST 

iv) POLAR, LOG, LINLOG, LOGLIN 

The optional arguments may appear in any order. The rule for evaluation of 
the optional args is as follows. If the argument is atomic it gets evaluated. 
The resulting arguments are the ones that get used. 

If you want to plot more than 3-4 curves on the same plot investigate 
using the N0T3D option to PL0T3D (see 18.4) 
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Examples 

PL0T2(SIN<X).X.-XPI,XPI); plots sln(X) against X as X takes on 

CALCOMPNUM values between -XPI to XPI 
PLOT2(X!,X,0,6. INTEGER); plots X! as X takes Integral values 

between and 6 
F(X):rSQRT(X); 

PLOT2(F(X),X,[-2, 3,100. 12J); plots F(X) as X takes the values in the 

values 1n the 11st 
PLOT2([X+l,X~2+l],X,-l,l); plots 2 curves on top of each other 

PL.OT2(y-funs,var-range,optionals-args) is the alternative form for PLOT2 y-funs 
must be a function of one argument or a list of functions of one argument. 
The functions must be either translated or compiled functions which return a 

,MT a ^f o P0,nl nUmber When ll is given f,oatjn e P° int ar « < or inte ger arg if the 
INTEGER arg to PLOT2 is given). This form of PL0T2 acts as though you had 
given a argument to the y-funs, and also specified that argument as the 
variable «n the form above. E.g. PL0T2<F,-2,'2)j acts like PLOT2(F(X) f X,-2,2); 
rnis is supposed to provide a quicker evaluation of the first arg and for that 
reason NO checking is done on the result. If the wrong kind of number is 
returned, the resulting plot will not be meaningful. 

TRANSLATE .TRUE; 

F(X): = (HODEDECLARE(X,FLOAT),EXP(-X»X)); 
PLOT2(F,-2,2); 

PLOT2(F,[-2,-l,0,l,2]); 

ARRAY(V, FLOAT, 10); 

FOR I FROM THRU 10 00 V[I]:FLOAT(I*I); 

PLOT2(F,V); 

GRAPH^x-lists^list^optional-args) plots points specified by the first x-lists and 
y-hsts. The format for x-lists can be one of 

i) [x-ptl t x-pt2, .. j<-pti, .. tX-ptn] where x-pti evaluates to a 
number 

ii) arrayname where arrayname is the name of a declared one- 
dimensional array of floating point numbers 



MACSYMA 18.2 Two-Dimensional Plotting 263 



iii) 2d-arrayname where 2d-arrayname is the name of a 
declared two-dimensional array of floating point numbers (i.e. 
by ARRM(2d-arrayname 9 FLOAT, max-row-index,max-col- 
index);) 

iv) [x-listl t x-li$t2, .. ,x-li$ti t .. ,x-listk] where x-listi can have 
the form of either i) or ii). 

The format of y-li$t$ is similar. The format of optional-args is the same as 
forPL0T2. 

Note that GRAPH2 performs the same job as the MACSYMA function 
MULTIGRAPH and that GRAPH2 is thus slightly incompatible with GRAPH FASL. 



PbRMAPLOT 2(x-exprs,y-expr$,variable,var-range,optional-args) plots x-exprs as 
the x coordinate against y-exprs as the y coordinate. 

The format for the first two arguments is the same as that for the first 
argument to PL0T2. Thus if x-exprs is [x-exprl, x-expr2, .. t x-expri, .. ,x- 
exprri] and y-exprs is [y-exprl f y-expr2, .. ,y-expri t .. ,y-exprk], then 
max(n,k) curves will be plotted. They will be (assuming n > k): 

x-exprl vs. y-exprl t .. ,x-exprk vs. y-exprk, 
x-expr(k+l) vs. y-exprk % .. t x-exprn vs. y-exprk 

the format for the remaining arguments is the same as for PL0T2. 



PARMAPLQT2(x-fun$.y-fun$,var-range,optional~args) efficiently evaluates its first 
2 arguments in the same way that the alternative form of PL0T2 works. 

Examples 

TRANSLATE: TRUE; causes automatic translation 

F(X) :=(MODEDECLARE(X, FLOAT), COS(X)); 

G(X) :=(MODEDECLARE(X, FLOAT), SIN(X)); 

PARAMPLOT2(F,G,0,2*%PI); plots F(x) vs 6(x) as x goes from to 2*%PI 

PARAMPLOT2(SIN(T),COS(T),T,0,2*XPI); 
plots sin(T) for the x-axis and cos(T) for the y-axis as T takes on CALCOMPNUM 
(see 18.2) values between and 2*%P\. (If EQUALSCALE is TRUE this draws a 
circle.) 
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CALCOMPNUM[20] is the number of points PL0T2 and PARAMPL0T2 plot when 
given the low,high type of variable range. The default if you load up 
PLOT2,LISP,D$K,SHARE is 20, which is sufficient for trying things out. 100 is a 
suitable value for a final hard copy. 



1 8.3 What to Type When PL0T2 has Finished Plotting 

When a plot is finished the bell on your terminal will be dinged (In fact, this 
happens only if WAIT is TRUE and if you're plotting on the terminal.) The plotting 
function is now waiting for you to type something before it exits and prints the 
next C-Label on your nice plot. It does nothing with most characters; they are 
left to be part of the next C-Line. However, the following characters are read 
and interpreted specially. 

space exits tn6 Dioiuns function. 

return clears the screen and then exits. 

tab causes the previous plot to be replotted. 

This is useful if the line is noisy, or, in conjunction with controt-A if 
various plotting parameters need to be changed 

linefeed sends out a hardcopy signal. 

At present this can only be used to generate hardcopy on the 
Tektronix hardcopy unit or on the Gould line-printer. 

rubout names the plot. 

PL0T2 types out "Enter name of plot" you reply ptotname; this is 
identical to typing a space instead of a rubout, followed by 
NAMEPLOTCp/ofoaroe);. 

controt-A 

This is not really read by the plotting function, but enables you to 
enter a controt-A break and change various options, before typing 
tab to have the plot replotted Make sure the plot has finished 
before you type this. 

PLOTBELL[TRUE] when FALSE inhibits the dinging of the bell. 

While your plot is coming out your terminal is in a rather strange state (e.g. not 
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echoing characters). Thus it is OK to type ahead to MACSYMA, but the ONLY way 
you should interrupt the plot is with control-*. E.g. do not use control-A until the 
plot has finished. 



1 8.4 Three-Dimensional Plotting 



PLOJ3D(z-expr$,x-var,var-range,y-var t varl-range,optional-arg$) makes a 3- 
dimensional plot of z-exprs against x-var and y-var. The plot consists of 
curves of y-exprs against x-var (the x coordinate) with y-var (the y 
coordinate) held fixed. Perspective is used and curves further away from the 
viewer have those parts of them which are hidden by the closer curves 
removed. 

The format of y-exprs is the same as for PLOT 2. The context of evaluation 
is FL0AT(EV( expr/,x-var=va/L/e gotten from var-range t y-var= value gotten 
from vari -ran#e,NUMER)). 

The format for var-range and varl -range is the same as for PL0T2 
except that if varl -range is of the form low,high then y-var will take on 
CALC0MPNUM1 values. 

The format of optional-args is the same as for PL0T2 except that 
additional options N0T3D, \3D, CONTOUR are available. 



PLOT3D(z-fun$ f var-range,varl-range f optional-arg$) is analogous to the alternative 
form for PL0T2. z-funs must be a function or list of functions of 2 arguments, 
which must return a floating point argument when given floating point (integer, 
if the INTEGER argument is used for either var-range or varl -range) 
arguments. The functions must be translated or compiled If you expect to 
make several 3D plots this form is recommended. 
A simple example is 

TRANSLATE: TRUE; causes automatic translation 

G(X,Y):=(MODECLARE(X, FLOAT), EXP(-X*X-Y*Y) ) ; defines a funtion G 
PLOT3&(G,-2,2,-2,2); plots 1t 
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GRAiPH3D(x-lists,y-list$,z-listsoptional-args) takes 3 arguments (GRAPH2 takes 2) 
and interprets them as lists of x, y, and z points which it uses to draw lines 
using the 3d transformations. It can be used to add lines (e.g. axes) to your 
3D plot. The hidden line routines are not used 

N0T3D 

In this section we describe the option N0T3D. As an example, consider 

PLOT3D(SIN(X)+A,X,-XPI,XPI,A,[-2 f 3,4,6],NOT3D) 

which plots sin(X)+A for X from -V.PI to XPI <CALC0MPNUM[20] points) and A 
taking the values in the list This is equivalent to: 

PLOT2([SIN(X)-2,SIN(X)+3,SIN(X)+4 t SIN(X)+6],X t -XPI,XPI) 

but requires less typing. 

The additional N0T3D argument to PL0T3D, causes exactly the same points as 
in the bare PL0T3D to be calculated Instead of plotting a 3-dimensionaJ 
representation of the data, the data Is plotted in a 2D one. Specifically 1 2D 
curve of z vs. x for each y value, and so is a convenient way to plot several 
curves on the same plot. 

PERSPECTIVE, REVERSE, VIEWPT, and CENTERPLOT 

The following options govern the type of perspective view given. 

PERSPECTIVE[TRUE], if FALSE causes a non-perspective view to be taken. 
This is equivalent to extending the viewing position out to infinity along a line 
connecting the origin and VIEWPT. 

REVERSE[FALSE], if TRUE cause a left-handed coordinate system to be 
assumed. 

VIEWPT and CENTERPLOT determine the perspective view taken. They are 
defaulted to be unbound VIEWPT may be set to a list of 3 numbers and gives 
the point from which the projection should be made. CENTERPLOT may likewise 
be set to a list of 3 numbers and gives a point on the line of sight. The 
projection will be made onto a plane perpendicular to a line joining VIEWPT and 
CENTERPLOT. 
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If VIEWPT and CENTERPLOT are unbound (the default) then they will be 
chosen as follows: the extreme values of the coordinates are determined. This 
gives the two points min: [xmin,ymin,zmin], max:[xmax,ymax f zmax]. CENTERPLOT is 
chosen as (min+max)/2, and VIEWPT is chosen as max+3*(max-min). The view is 
then one in which the z axis is vertical, the x axis is increasing towards you to 
the left and the y axis is increasing towards you to the right 

If CENTERPLOT is FALSE then the old type of perspective view will be given 
(like setting the x and z components of CENTERPLOT to the corresponding 
components of VIEWPT). 



18.5 Using the XGP from PL0T2 



To get plots out on the XGP, simply do PLOTMODE(XGP, ...) where ... is the 
correct plot mode for your terminal (i.e. GR for Grinnell TV's, T for Tektronix, or D 
for character display terminals like VT52 5 s). Then you can use linefeed at the end 
of the display of a plot, or HARDCOPYO; to cause a hardcopy to be submitted to 
the XGP (it is processed by the Gouid spooler first), if MIT-AI* is up and the 
queuing for the XGP is successful, you will receive a message from the XGP 
spooler when your plot is printed. If MIT-AI is down, your plot will be processed 
into an XGP scan file, .GLPT.; > SCN, and the Gould spooler will send you a 
warning message telling you that MIT-AI is down. You must copy the SCN file to 
MIT-AI yourself when MIT-AI comes up and queue it by doing 

:XGP ;SCAN Alrdir;* SCN 

where dir is the directory on MIT-AI to which you copied the files (use MACSYM; 
if you don't know of any other directory to use). 

If you use the NAMEFILE 2 command instead of HARDCOPY or linefeed, you can 
print the plot file later by doing 

:GTPL d1r;fnl fn2/a/o[x] 

where dir, fnl, fn2 are the directory, first file name, and second file name of the 
plot file stored with NAMEFILE. PL0TLFTMAR£128] and PL0TB0TMAR[320] 



1. The computer at the MIT Al Lab 

2. NAMEFILE(filespec) simply copies the PL0T2 scratch file to filespec 
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adjust the bottom margin and left margin for the XGP plots. These default to 
values 3 such that the plots will fit comfortably on an 8 1/2 x 1 1 page. 

There are many other features of PL0T2 (such as three-dimensional and 
contour plotting) which the user can learn about by reading SHARE;PL0T2 USAGE 
and SHARE ; PL0T2 RECENT, As an example, consider 

(PLOThOOE(X6P,O),WINW)W:[100,900 f 0,9503)t 

(CALCOMPNUH:CALCOHPNUHl:40,VIEWPT:[-30,-20,5])t 

X,-3,3,Y,-3,3); 
NAMEFILE(PLOT,TEST,DSK,CFFK); 
The resulting plot is shown on the next page 



3. Whose units are given in increments of 1/200 th of an inch 
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19 Debugging in MACSYMA 

When the user's command lines, especially functions and BLOCK programs, do 
not do what is expected or generate errors, MACSYMA offers several debugging 
alternatives: 

(1) The user may trace function calls by typing lHkQ£(funl t fun2,...) t where 
the turn are either MACSYMA or user-defined functions. This will cause a printout 
of the function name and its arguments each time it is entered, and of the function 
name and the value it returns each time it is exited. A count which is the level of 
recursion is also printed. Usually, this is all the tracing power the user will need, 
although MACSYMA offers the full capabilities of the LISP tracing package including 
conditional and breakpoint tracing. This will not be described here - for 
information see [Mnl]. MACSYMA uses trace-syntax very similar to that of LISP. 

To check which functions are currently under trace, the user may type 
TRACEO. To remove tracing of functions use \JmRAC£(funl,fun2^.). To untrace 
all prev,ously traced functions type UNTRACEO. Since the TRACE package takes 
up some of the user's workspace in core, when finished with it the user should 
type REMTRACEO. It can always be reloaded again if necessary. 

(2) The assignment of variables can be traced by setting the variable 
SETCHECK to a list of variables (which can be subscripted). When a variable on 
the list is bound (either with : or :: or function argument binding) then a message 
— variable "SET TO" value — will be printed. If the variable SETCHECKBREAK is 
set to TRUE then a (MACSYMA-BREAK) will be caused each time a variable on the 
SETCHECK list is bound. 

(3) By setting the variable REFCHECK[FALSE] to TRUE, the user will be 
informed when each of his variables which has a value comes up for evaluation for 
the first time during the course of a computation. This has a dual purpose. The 
user will be informed of evaluations he may not have been aware of which are 
the result of assignments he made long ago. It also gives him a sort of 
chronological trace of his computations which may be helpful in finding out where 
an error has occurred. 

(4) By setting the variable PREDERROR to TRUE, the user will be informed of 
predicates of IF-THEN-ELSE statements which failed to evaluate to either TRUE or 



r- A l r*r- 



(5) The user may have variables which he intends not to use purely 
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symbolically, i.e. they are to have values all the time. By typing 
DECLARE([vari,var2,...lBINDTEST) MACSYMA will give the user an error 
whenever any of the vari appear in a computation unbound. To remove a 
BINDTEST declaration, the user may use the function REMOVE, (see 8.1) 

(6) When an error occurs in the course of a computation, MACSYMA prints 
out an error message and terminates the computation. At times the user may find 
it helpful to investigate the environment at the place of the error. To do so, type 
DEBUGMODE:TRUE or DEBUGMODE:ALL and repeat the computation. This enters a 
special debugging mode which will "break" or pause when an error occurs. This 
mode may be terminated by typing DEBUGMODE:FALSE. When an error occurs in 
debugging mode, (ERROR-BREAK) is printed. MACSYMA is then waiting for the 
user to type something. He may type any command line just as if he were at "top 
level". The command lines will be evaluated in the environment of the error. If 
the user had done DEBUGMODE:ALL, he may now type BACKTRACE;, and 
MACSYMA will print out a backtrace, which is a list of the function calls the user 
is currently in together with the arguments they were called with, ordered from 
most recent to earliest i.e., when reversed, this list shows a trace beginning from 
the initial function and ending at the last call entered including only those function 
calls from which the user still has not exited. To exit from the MACSYMA error- 
break and return to "top-level", type EXIT;. 

The user may also enter the error-break at any point, by typing control-A or 
by executing the function BREAK (see 10.6). This will simply cause his 
computation to pause, while he investigates at will. %% refers to the last 
computed result while in the MACSYMA break. % still refers to the last result 
computed at top-level. Upon typing EXIT;, the computation will resume. If he 
wants to quit a computation begun in a control-A break without quitting the top- 
level suspended computation, the user can type control-X. 

During a break one may type TOPLEVEL;. This will cause top-level 
MACSYMA to be entered recursively. Labels will now be bound as usual. 
Everything will be identical to the previous top-level state except that the 
computation which was interrupted is saved. The function T0BREAK0 will cause 
the break which was left by typing TOPLEVEL; to be re-entered. If TOBREAK is 
given any argument whatsoever, then the break will be exited, which is equivalent 
to typing TOBREAKO immediately followed by EXIT;. 

In the following example, an attempt is made to define a function ROOT which 
finds an approximate root to an expression using Newton-Raphson iteration. 
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(Cl) ROOT(F.V):=BIOCK([VAL,FUN,DER],DER:DIFF(F.V),VAL:0.0, 
TEST t FUN:SUBST(VAL,V,F),IF ABS(FUN)<5.0E-7 THEN 
RETURN(VAL).DER:SUBST(VAL.V,DER) f VAL:VAL-FUN/DER, 
G0(TEST))S 

(C2) NUMER: TRUES 

<C3) F:SIN(XPI*X)-%PI*(X-1)S 

<C4) ROOT(F.X); 

3.3116898E+8 AR6 TOO BI6 FOR ACCURACY - SIN 

(C5) 0EBU6: TRUES 

(C6) DEBUGHODE: TRUES 

<C7) "C4; 
F has value 
V has value 
VAL has value 
FUN has value 
DER has value 

3.3116898E+8 ARG TOO BIG FOR ACCURACY - SIN 

..(ERROR-BREAK) 

-VAL; 
1.0541436E+8 

-DER; 

- 2.98023224E-8 

_TRACE(SUBST)S 

_"C4; 



< i ne numerical value of %Pi is present below due to NUMER being set to TRUE 
above.) 
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1 ENTER SUBST [0.0, X, SIN(3. 1415927 X) - 3.1415927 (X - 1)] 

1 EXIT SUBST: 3.1415927 

1 ENTER SUBST [0.0, X, 3.1415927 COS(3. 1415927 X) - 3.1415927] 

1 EXIT SUBST: - 2.98023224E-8 

1 ENTER SUBST [1.0541436E+8, X, SIN(3. 1415927 X) - 3.1415927 (X - 1)] 

3.3116898E+8 ARG TOO BIG FOR ACCURACY - SIN 

try again 

(This message is due to an error-break occurring within another error break.) 

_EXIT; 

EXITED FROM THE BREAK 

(C8) <t> 

_"C4 

MYFROOT<*><*> 



(The user uses the MYF command of the MACSYMA editor to insert the definition 
of ROOT into the edit buffer. The editor is then used to insert an IF statement to 
test for DER being close to 0. The actual editing work is not shown.) 

(C8) ROOT(F,V):=BLOCK([VAL,FUN,DER],DER:DIFF(F,V,1),VAL:0.0, 
TEST,FUN:SUBST(VAL,V,F),IF ABS(FUN)<5.0E-7 THEN 
RETURN(VAL),DER:SUBST(VAL,V,DER),IF ABS(DER)<5.E-8 
THEN ERR0R( "DERIVATIVE IS ZERO"),VAL:VAL-FUN/DER, 
GO(TEST))t 

(C9) UNTRACEO; 

(D9) [SUBST] 

(C10) DEBUG:FALSEf 

(Cll) "C4; 

DERIVATIVE IS ZERO 

QUIT (This 1s due to the ERROR function being executed.) 
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Appendix I - Multics MACSYMA 



MACSYMA is also implemented on the Multics operating system which runs on 
Honeywell Series 60 machines (the 68/80 in particular). It is the same MACSYMA 
as on the ITS system; the only differences that exist are due to the interaction of 
the LISP in which the MACSYMA is imbedded with a different operating system. 
Since this manual is mainly written for using a MACSYMA on ITS, one has to be 
aware of these differences if one is to use the manual while using a MACSYMA on 
Multics. 

Procedures for logging in and out will not be given here. It is assumed that if 
one has access to a Multics one will either know the procedures for logging in or 
will be able to obtain adequate documentation in order to learn how to do so. 

1) To use a MACSYMA on a Multics one simply invokes the "macsyma" 
command. However since this command may not be in one's default search rules, it 
may be necessary to link to the command or to refer to it by its full pathname. 
For example, on the Multics at MIT, the full pathname of the command is 
**>udd>ap>library>macsyma". 

When the command is invoked, the MACSYMA system is loaded and prompts 
the user in the standard manner. 

2) All input must end with a newline (return) after the semi-colon or dollar- 
sign is typed. 

3) The terminator character for the editor is "8T instead of altmode. 

4) Control characters are not entered in the manner described in the rest of 
this manual but are instead entered by the conventions of the Multics 
implementation of LISP. This is done by using the "attention- or "break" button on 
the console followed by the letter of the alphabet for the control character you 
want, followed by a newline character, i.e. when you hit the attention key, the 
system will type "CTRL/", and you should respond by typing the appropriate 
character. If you want a control-Z, for example, you would type the letter "Z" 
followed by a newline. The various control characters have the same meaning as 
on ITS MACSYMA. The only one that is different is control-Z which rather than 
"returning" to a monitor level instead calls a new invocation of the monitor at a 
higher levei i.e. it is ihe same thing as a normai Muitics quit signal. A *starr 
command will start the macsyma moving again. 
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5) There are two different ways of referring to files in the Multics hierarchy. 
MACSYMA commands that take file names as arguments can be given the Multics 
file name enclosed in double quotes as a single argument. An alternative form of 
reference is one that maps the ITS way of referring to files with four arguments 
into a reasonable Multics filename. Thus: 

(cl) batch( "random. demo"); 

(cl) batch(">udd>Project>JRNurd>random.demo"); 

(cl) batch( random, demo); 

(cl) batch(random,demo,dsk,">udd>Project>JRNurd"); 



would all refer to the same file if the current working directory were 
w >udd>Project>JRNurd M . 

(6) To use the Multics plotting package, set the variable MULTGRAPH to 
TRUE. 
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Appendix II - A MACSYMA Grammar Primer 

The concepts MACSYMA deals with are primarily mathematical, and its 
grammar has been designed to reflect this emphasis by making the representation 
of expressions as natural as possible. All the usual mathematical operators are 
predefined, and MACSYMA commands are expressed exclusively in functional 
notation. In addition, MACSYMA provides a flexible syntax extension capability for 
users who require additional operators. 

For the purposes of this appendix, the internal representation of a MACSYMA 
expression can best be described in terms of function calls. All expressions are 
represented as appropriately nested function calls; all actions are the result of 
function evaluations. This primer is intended to introduce the reader to 
MACSYMA's syntax and and syntax extension capabilities and to help him utilize 
these features most effectively in syntactically expressing the semantics of the 
job he wants done. 

It is assumed here that the reader is already familiar with the rules of 
formation for lexemes, i.e. integers, real numbers, atoms, and strings. At present 
these rules are somewhat confusing and should be mastered before proceeding 
(see 2.3) . 

The Parser 



When a user types a string of characters to MACSYMA, it is first broken up 
into lexemes by a lexical-scanning program For example the input "IF X>0 THEN 
X ELSE -X" becomes (IF X > THEN X ELSE - X). This sequence of lexemes is 
then passed to an "extended operator precedence parser with types" and 
converted into MACSYMA's internal representation, i.e. suitably nested function 
calls. In this case, the result would be as follows: 



"IFV^X.O.X."-"^ 



Such functional notation is always legal MACSYMA syntax, and it will be used 

throughout this annendix. as ahnve tn ronraeont tho »**«•%;■*» m< %,*»:«» .~ ~w«t~_i:- 
constructions. 
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Every lexeme in MACSYMA is either an "operator", a "delimiter", or an 
"operand". The operators and delimiters taken together are sometimes referred 
to as the "keywords" of MACSYMA. With each operator is associated a specific 
parsing function which prescribes how its arguments are to be selected from the 
input. Thus, for example, the arguments of an infix operator like ">" are to be 
found, one to the left and one to the right of the operator. The resulting internal 
representation is a function call of the operator on its arguments. For example, in 
the sentence above, ">" has as arguments "X" and "0", and the internal 
representation of "X>0" is ">"<X,0% 

A delimiter is a reserved lexeme used by certain operators to mark their 
arguments. A delimiter may not be used as an operand but has no special parsing 
function associated with it. In the sentence above, "THEN" and "ELSE" are 
delimiters, used by the operator "IF" to mark its second and third arguments. 

An operand is a lexeme with no special parsing properties. All lexemes, 
unless otherwise specified, are operands. Operands serve as the arguments of 
operators to form function calls which may then In term serve as arguments to 
other operators. In the example sentence, "X" and "0" are operands; ">"(X,0), X, 
and "-"(X) also appear as operands to the operator "IF", Note that any operator 
may be used as an operand by enclosing it in double quotes, e.g. INFIX("&"). 

The process of parsing is one of recognizing the operators, delimiters, and 
operands in a sequence of lexemes and correctly identifying the arguments to the 
operators in order to construct the function nesting implicit in the sequence. 
There are only seven types of operators in MACSYMA, most of which should be 
familiar to mathematicians. These seven types are described below. 



PREFIX OPERATORS 

A PREFIX operator is one which signifies a function of one argument, which 
argument immediately follows an occurrence of the operator. Some examples are: 

NOT TRUE means "NOT" (TRUE) 

- A means "-" (A). 

This resembles the usual functional notation except that the parentheses 
surrounding the argument are here unnecessary. Of course any expression may 
be embedded to arbitrary depth within another as in the following. 
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NOT NOT TRUE means "NOT" ("NOT" (TRUE)) - TRUE 

POSTFIX OPERATORS 

POSTFIX operators like the PREFIX variety denote functions of a single 
argument, but in this case the argument immediately precedes an occurrence of 
the operator in the input string. 

3! means T(3) 

A !! means "!T (A) 

INFIX OPERATORS 

INFIX operators are used to denote functions of two arguments, one given 
before the operator and one after. Again some examples: 

A~2 means " A " (A,2) 

3"3 > 10 means ">" <•*" (3,3), 10) 

A variation of the INFIX operator is the NARY. 

NARY OPERATORS 



An NARY operator is used to denote a function of any number of arguments, 
each of which is separated by an occurrence of the operator. 

A*B*C means V (A,B,C) 

A>B AND TRUE AND C<D means "AND"(">"(A,B),TRUE,"<"(C,D)) 

are all examples of NARY operators. 



SPECIAL OPERATORS 
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NARY operators are useful for functions whose arguments are in one way or 
other homogeneous. For other functions of many arguments, special forms are 
required. A familiar example is the conditional statement. 

IF A>2 THEN A-l ELSE A means "IFT>"<A,2),"-"(A,1),A) 

Here the operator "IF" denotes a function of three arguments; the first is 
found immediately after the "IF"; the others are introduced arguments signalled by 
the occurrence of the delimiters associated with "IF", namely "THEN" and "ELSE". 
Once again, delimiters are not in themselves operators but are merely used by 
operators to mark introduced arguments. Using a delimiter out of the context of 
the operators for which it was defined will result in a syntax error. 

Another example of an operator with introduced arguments is the iteration 
statement. Here the delimiters precede their defining operator. 

FOR I FROM 2 STEP 3 THRU 10 UNLESS A>10 DO PRINT(A) 



In this example each of the indicated segments contributes an argument to the 
"DO" function. It happens that in MACSYMA any of these arguments may be 
omitted, or if given they can be given in any order. Thus the following are all 
legal, though not necessarily equivalent, sentences. 

THRU 10 DO S:S*2 

FOR I FROM 2 THRU 5 DO PRINT (A[I]) 

THRU 5 UNLESS AM000 DO A:A! 



When arguments are omitted as above or like the "ELSE" argument of the "IF" 
operator, the corresponding "holes" are filled with predetermined default values. 
These are listed in the dictionary below. Also the "DO" statement has some 
additional flexibility. The "STEP" argument can be replaced by a "NEXT" 
expression which denotes what the iteration variable is to be set to on each pass 
thru the loop rather than the value by which it is to be incremented; and there 
are permitted arbitrarily many "WHILE" or "UNLESS" clauses as termination 
conditions. Some examples with answers; 

THRU 3 DO PRINT (A) 

A 

A 

A 

DONE 



280 II A MACSYMA Grammar Primer MACSYMA 



FOR I STEP 2 THRU 3 DO PRINT (I) 

1 

3 

DONE 
FOR I NEXT 1*2 UNLESS I>3 DO PRINT (I) 
1 
3 

DONE 



NOFIX OPERATORS 

NOFIX operators are used to denote functions of no arguments. The mere 
presence of such an operator in a sentence will cause th© corresponding function 
to be evaluated 

QUIT means "QUIT () 

LOGOUT means "LOGOUT" () 

Care should be taken in using these operators, however, since they tend to 
look much like variables but semantically are very different 

MATCHFIX OPERATORS 



MATCHFIX operators are used to denote functions of any number of 
arguments which are passed to the function as a list The arguments occur 
between the main operator and its "matching" delimiter. For example: 

[) A, B, C (] means [)" <A,B,C) 

A legal sentence in MACSYMA is a correct sequence of operators from these 
seven categories and their operands. By "correct" here we mean that due 
respect has been shown the type of the operator, e.g. not giving two arguments 
to a PREFIX operator, and that the two sole grammatical rules in the language 
have not been violated. These rules concern the "binding powers* of MACSYMA's 
keywords and the "parts of speech" legal in each argument slot 
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BINDING POWERS 



The binding powers of keywords are used to resolve ambiguities of argument 
association such as that in the following example. 



- 233 ! 



Is this W -Vr<233)) or T("-"<233)); or, in other words, which operator gets 
the operand "233- and which, the resulting function call? It is a convention in 
MACSYMA that the keyword with the higher binding power gets the disputed 
argument and the other is then applied to the result. In this case, the "left binding 
power" of T (160) is greater than the "right binding power" of "-" (100); and so 
"233 M is associated with T and the resulting function call becomes the argument 
for "-" 

i_ach keyword must possess a left and a right binding power to resolve such 
conflicts. Some of these numbers are superfluous, such as the left binding power 
of a prefix operator; and in such cases the binding power is arbitrarily taken to be 
200. Currently the range of binding powers is to 200. 



PARTS OF SPEECH 



From natural language the notion of "part of speech" should be familiar. 
MACSYMA also has parts of speech and constraints on which parts of speech are 
legal in various contexts. Whereas binding powers are necessary to resolve 
ambiguities af argument assignment, parts of speech exist solely to detect 
unintentional syntax errors. 

Every operator possesses a part of speech constraint on each of 
its argument slots. Any operand filling a slot must satisfy the 
associated constraint, or a syntax error will result 

There are only three parts of speech predefined in MACSYMA, namely EXPR, 
CLAUSE, and ANY. An EXPR is essentially a mathematical expression; a CLAUSE, a 
mathematical predicate or a command. Thus "A+B" is an EXPR but not a CLAUSE; 
and "A+B>2" is a CLAUSE but not an EXPR. The part of speech ANY is used to 
signify objects which may be either CLAUSES or EXPRs, such as "F(X)". The parts 
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of speech required by MACSYMA's predefined operators are Hated in the 
dictionary below. 



SYNTAX EXTENSION 

While MACSYMA's syntax should be adequate for most ordinary applications, 
it is possible to define new operators or eliminate predefined ones that get in the 
user's way. The extension mechanism is rather straightforward and should be 
evident from the examples below. 

(CI) PREFIX("DDX")S 

(C2) DDX Yt means "D0X"(Y) 

(C3) INFIX("<-")i 

<C4) A<-DDX Yt means "<-"(A,"00X"(Y)) 



An appreciation of the concepts and rules introduced in this primer should be 
all that is necessary to use the syntax extension capabilities successfully. The 
only form of syntax extension available is the definition of new operators. For 
each of the types of operator except SPECIAL, there is a corresponding creation 
function that will give the lexeme specified the corresponding parsing properties. 
Thus "PREFIXCDDXT will make M DDX M a prefix operator just like "-" or "NOT". 
Of course, certain extension functions require additional information such as the 
matching keyword for a matchfix operator. In addition, binding powers and parts 
of speech must be specified for all keywords defined. This is done by passing 
additional arguments to the extension functions. If a user does not specify these 
additional parameters, MACSYMA will assign default values. The six extension 
functions with binding powers and parts of speech defaults (enclosed in brackets) 
are summarized below. 
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PREF\X(operator, rbp[l80l rpo$[ANY], pos[ANY]) 

POSTF\X(operator, !bp[180], lpo$[ANY} pos[ANY]) 

\HF\X(operator, fbp[180J, rbp[l80l lpo$[ANY% rpo$[ANYJ, pos[ANYJ) 

MRY(operator, bp[180i argpo$[ANYl po$[ANYJ) 

NOF\X\opera\or(po$[ANY]l) 

MkTCHF\X(operator, match, argpo$[ANY], pos[ANYJ) 

The defaults have been provided so that a user who does not wish to 
concern himself with parts of speech or binding powers may simply omit those 
arguments to the extension functions. Thus the following are all equivalent. 

PREFIX( "DDX" , 180 , ANY, ANY)t 

PREFIX("DDX\180)t 

PREFIX("DDX")t 

It is also possible to remove the syntax properties of an operator by using 
the functions REMOVE or KILL Specifically, "REMOVECDDXTFr or "KIH-CDDX")" 
will return W DDX M to operand status; but in the second case all the other 
properties of M DDX" will also be removed. 

The following is an example of syntax extension to permit the use of set 
notation. 

(Cl) MATCHFIX("{","}")i 

<C2) INFIX("|")t 

(C3) {X|X>0>; 

(D3) {X|X>0} 

(C4) {X|X<2}; 

(04) {X|X<2} 

(C5) INFIX(".U.")t 

(C6) INFIX(".I.")S 
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Now assuming the functions "U." and "I." have been appropriately defined as 
union and intersection, the following interaction can occur. 
(C7) D3.U.D4; 

(07) UNIVERSE 

(C8) D3.I.D4; 

(08) (X|X>0 AND X<2) 

<C9) {1.2. 3)1 

(CIO) {3,4,5)1 

(Cll) 09.U.D9.I.D10; 

(Oil) {3) 

Line CU was parsed as ((D9.U.D9UD10) whereas the usual convention 
would call for the alternate parsing (D9.U.(D9.I.D10)), which would have resulted in 
•1,2,3} as value. The problem here is that the default binding powers for ".U." 
and "I." are identical; so the parser associates them in left to right order. To 
obtain the usual parsing, the syntax definitions in lines C5 and C6 must give ".I." a 
higher left binding power than n .U. m 9 right binding power as in the following. 
(C12) INFIX(".U. ",100,100)1 

(C13) INFIX(".I.",120,120)t 

(C14) D9.U.D9.I.010; 

(014) (1,2,3) 

(C15) REMOVE( M .U.\ OPERATOR)! 

(C16) D9.U.D10; 
Syntax error 
09 . U. ******* 010 
Please rephrase or edit 

A DICTIONARY OF MACSYMA'S KEYWORDS 

The following is a list of all the keywords in MACSYMA, categorized with 
respect to type. With each keyword is given the information necessary to 
recreate its syntactic behavior. The abbreviations "ibp", "rbp", "ipos M , "rpos", 
"bp", ana "pos" stand for "left binding power", "right binding power", left part of 
speech", "right part of speech", "binding power", and "part of speech". The 
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reader should consult the text of this primer to understand the significance of 
these parameters. It should also be noted that some lexemes, like M - n , have two 
syntactic types. 



NOT 



PREFIX OPERATORS 




rbp rpos 


pos 


190 ANY 


ANY 


190 ANY 


— 


100 EXPR 


EXPR 


100 EXPR 


EXPR 


70 CLAUSE 


CLAUSE 



POSTFIX OPERATORS 
Ibp Ipos pos 



f 

• 


160 


EXPR 






EXPR 


ff 

• • 


160 


EXPR 






ANY 








INFIX OPERATORS 






Ibp 


Ipos 


rbp 


rpos 


pos 


# 


80 


ANY 


80 


ANY 


CLAUSE 


** 


140 


EXPR 


139 


EXPR 


EXPR 


. 


130 


ANY 


129 


ANY 


ANY 




180 


ANY 


20 


ANY 


ANY 


• • 


180 


ANY 


20 


ANY 


ANY 


:= 


180 


ANY 


20 


ANY 


ANY 


< 


80 


EXPR 


80 


EXPR 


CLAUSE 


<= 


80 


EXPR 


80 


EXPR 


CLAUSE 


= 


80 


EXPR 


80 


EXPR 


CLAUSE 


> 


80 


EXPR 


80 


EXPR 


CLAUSE 


>= 


80 


EXPR 


80 


EXPR 


CLAUSE 


S\ 


140 


EXPR 


139 


EXPR 


EXPR 


^/\ 


135 


ANY 


134 


ANY 


ANY 
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MACSYMA 







NARY OPERATORS 






bp 


argpos 


P09 


* 


120 


EXPR 


EXPR 


+ 


100 


EXPR 


EXPR 


1 


10 


ANY 


ANY 


- 


100 


EXPR 


EXPR 


/ 


120 


EXPR 


EXPR 


AND 


60 


CLAUSE 


CLAUSE 


OR 


50 


CLAUSE 


CLAUSE 



( 

[ 

DO 



IF 



Ibp 



SPECIAL OPERATORS 



Ipos 



rbp 



rpos 



pos 



200 ANY 

200 ANY 

200 

FOR 

FROM 

IN 

STEP or NEXT 

THRU optional 

WHILE 

UNLESS 

200 

THEN 

ELSE 



MATCHFIX for right arg ANY 

MATCHFIX for right arg ANY 

25 ANY ANY 

optional 

optional 

optional 

optional 

any number of occurrences 
any number of occurrences 
45 CLAUSE ANY 

optional 



MA TCHFIX OPERA TORS 



match 



argpos 

ANY 
ANY 



pos 

ANY 
ANY 



MACSYMA 
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DELIMITERS 


• 




op 


Ibp 


rbp 


rpos 


ELSE 


IF 


5 


25 


ANY 


FOR 


DO 


30 


200 


ANY 


FROM 


DO 


30 


95 


EXPR 


IN 


DO 


30 


95 


ANY 


NEXT 


DO 


30 


45 


ANY 


STEP 


DO 


30 


95 


EXPR 


THEN 


IF 


5 


25 


ANY 


THRU 


DO 


30 


95 


EXPR 


UNLESS 


DO 


30 


45 


CLAUSE 


WHILE 


DO 


30 


45 


CLAUSE 
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Appendix III - Illustrative Examples 



This appendix shows a complete interaction with MACSYMA. Three examples 
are given. First an ordinary second-order differential equation is solved by two 
methods. ( 1 ) by using pattern matching and solving the characteristic equation and 
(2) by using Laplace transforms. The second example shows the conversion of an 
expression from one coordinate system to another and the third example shows a 
truncated power series solution of a differential equation. 



Example 1 

(CI) BATCH(SOLDER,DEHO.DSK,DEHO); 

<C2) /* THE FOLLOWING ROUTINE RETURNS THE HOHOG.-PART SOLN 
TO 2ND ORDER LINEAR DIFF'L EQNS. WITH CONST. COEFFS. */ 

MATCHDECLARE([B.CJ,RATNUHP)$ 

MATCOM FASl OSK MACSYM BEING LOADED 
LOADING DONE 

<C3) MATCHDECLARE(F,FREEOF(U))l 

<C4) ALIAS<D,DIFF)t 

(C5) DEFMATCH(S0LDE,'D(U,X,2) ♦ B*'D(U.X) ♦ C*U * F,U,X)I 
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(C6) SOLDER(EQN,U,X) := 

BL0CK([B,C,F,DISC,R1,R2,ALPHA,BETA], 

IF SOLDE(EQN,U,X) = FALSE THEN RE TURN (FALSE), 

DISC: B A 2 - 4*C, ALPHA: -B/2, 

IF DISC=0 THEN RETURN(XE A (ALPHA*X)*(A1+A2*X)), 

BETA: SQRT(DISC)/2, 

IF DISC > 

THEN (Rl: ALPHA + BETA, R2: ALPHA - BETA, 

RETURN(A1*XE A (R1*X) ♦ A2*XE A (R2*X))) 
ELSE (BETA: SQRT(-1)*BETA, 

RETURN(XE A (ALPHA*X) * (A1*C0S(BETA*X) 
♦ A2*SIN(BETA*X)))))f 

(C7) /* AN EXAMPLE - THE METHOD OF UNDETERMINED COEFFS. FOR 
OBTAINING THE PARTICULAR SOLN. AS WELL */ 

DE: 'D(Y,X,2) - 'D(Y.X) - 6*Y « SIN(X); 

2 
D Y OX 

(07) 6 Y s SIN(X) 

2 DX 

DX 

(C8) YH(X) :» "(SOLDER(X,Y,X)); 

- 2 X 3 X 

(08) YH(X) :* A2 XE ♦ Al XE 

(C9) YP(X) := B1*SIN(X) + B2*C0S(X)t 
(CIO) YG(X) :r YH(X) ♦ YP(X)t 
(Cll) PLUGIN: EV(DE,DIFF f EXPAND,Y*YP(X)); 
(Dfl) B2 SIN(X) - 7 Bl SIN(X) - 7 B2 COS(X) 

- Bl COS(X) = SIN(X) 
(C12) EQN1: COEFF(PLUGIN,SIN(X)); 
(012) B2 - 7 Bl = 1 
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(C13) EQN2: C0EFF(PLU6IN,C0S(X)); 

(013) - 7 B2 - Bl « 

(C14) GLOBALSOLVE: TRUES 

(C15) SOLN: LINS0LVE([EQN1,EQN2],[B1,B2]); 
SOLUTION 

7 
(E15) Bl : - — 

50 

1 
(E16) B2 : — 

50 

(016) [E15, El*] 
(C17) Y6(X); 

7 SIN(X) COS(X) 3 X - 2 X 

(017) ♦ ♦ Al XE ♦ A2 XE 

50 50 

(C18) /* PLUGGING IN INITIAL CONDITIONS OF Y(0)«1 
AND Y'(0)»0 */ 

EQN1: YG(O) =1; 

1 

(018) A2 ♦ Al ♦ -- * 1 

50 

(C19) DIFF(YG(X),X); 

SIN(X) 7 COS(X) 3 X - 2 X 

(D19) ♦ 3 Al XE - 2 A2 XE 

50 50 

(C20) EQN2: EV(X,X=0) = 0; 

7 
(020) - 2 A2 ♦ 3 Al - — * 

50 
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(C21) SOLN: LINS0LVE([EQN1,EQN2L[A1.A2J); 
SOLUTION 



(E21) 

(E22) 
(D22) 

(C23) YG(X); 

3 X - 2 X 
7 SIN(X) COS(X) 21 XE 14 XE 
(D23) ♦ ♦ .-.-.. «. . — . 

50 50 50 25 
(C24) /* RESETTING OF OPTIONS */ 

GLOBALSOLVE: FALSE! 
(025) BATCH DONE 





21 


Al 


• 




50 




14 


A2 


• 




25 


[E21, 


E22] 



(C26) "SOLUTION BY LAPLACE TRANSFORHS-i 

(C27) SUBST(Y(X),Y,DE); 

2 
D 
(0?7) ... Y (X) - -- Y(X) - 6 Y(X) * SIN(X) 
2 OX 
DX 

(C?8) [ATVALUE(Y(X),X=0,1), ATVALUE(^DIFF(Y(X) f X) f X«0,0)]; 
(028) [l, 0] 
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(C29) LAPLACE(D29,X,S); 



LAPLAC FASL DSK MACSYH being loaded 
loading done 



2 
(D29) S LAPLACE(Y(X), X. S) - S LAPLACE(Y(X), X, S) 



1 

- 6 LAPLACE(Y(X), X, S) - S ♦ 1 

2 
S ♦ 1 

(C30) LINSOLVE([%],£aAPLACE(Y(X),X,S)]); 
Solution 

3 2 

s - s ♦ s 

(E30) LAPLACE(Y(X), X f S) * 

4 3 2 

s -s - 5 s - s - e 

(030) [E30] 

(C31) ILT(E30 § S,X); 

3 X -2X 
7 SIN(X) COS(X) 21 XE M XE 

(031) Y(X) = ♦ ♦ ♦ 

50 50 50 25 
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Example 2 

(CI) BATCH(C2CYL,DEM0,DSK,DEM0); 

(C2) /* CONVERSION OF THE LAPLACIAN FROM CARTESIAN COOROS. TO 
CYLINDRICAL COOROS. */ 

/* CAUSE DERIVATIVES TO DISPLAY WITH SUBSCRIPTS */ 

DERIVABBREV:TRUEi 

(C3) /* ORDER X,Y, AND Z SO THEY WILL BE GROUPED NICELY */ 

ORDERLESS(Z,Y,X)i 

(C4) /* U(X,Y,Z) BECOMES U(R,T,Z) IN CYLINDRICAL COORDINATES 
R STANDS FOR RHO AND T FOR THETA */ 

DEPENDS(U,[R,T,Z])i 

(C5) /* INPUT THE TRANSFORMATION RULES FROM THE 
CARTESIAN SYSTEM TO THE CYLINDRICAL SYSTEM */ 

GRADEF(R,X,X/R)t 

<C$) GRADEF(R,Y.Y/R)S 

(C7) GRADEF(T,X,-Y/R~2)t 

(C8) GRADEF(T,Y,X/R*2)i 

(C9) /* SET EXPOP TO CAUSE PARENTHESIZED EXPRESSIONS 
TO BE EXPANDED AUTOMATICALLY */ 

EXPOP: It 
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(CIO) /* NOW JUST INPUT THE LAPLACIAN IN CART. COORDS., 
AND LET THE CHAIN RULE DO ITS THING */ 

DIFF(U,X,2)+DIFF(U,Y,2)+DIFF(U,Z,2); 

2 2 2 2 2 2 

X U Y U X U Y 2UXUYU 

T T T T M R R R R R 

* 4 2 2 R 3 9 ZZ 

R R R R R R 

(Cll) SUBST(IT2-)r2 v Y»2,%): 

U U 

T T 1 

(Dll) ♦ U ♦ — ♦ U 

2 R R R I Z 

R 

(D12) BATCH DONE 
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Example 3 

The following differential equation: 

T^4*«T)^3*DIFF(B(T) f T;2)4{l-K # T A 2>»B(7) A 4-T^4-0- 
is known to have a solution of the form: 

B(T)=T+A3*-r3+A5*r5+...+Al 1*T~1 1+... 
valid for small T. The problem is to find the coefficients A3 through All as 
functions of K We use RATWEIGHT and RATWTLVL to truncate on powerV of T 

Go^ti 4 '^ jn " Bessel Functl °" 8 foJHS* Arguments 2 by 

Goldstein and Thaler, in Math. Tables and Other Aids to Computation, (now called 
Mathematics of Computation) XII, no. 61, p.18, January 1958.) 

<C3) E0:T^4*B(Tr3*DIFF(B(T),T,2)+(l-K*r2)»B(Tr4.r4; 

2 
4 3 D 24 4 

< 03 > T B (T) (--- B(T)) M1-U)I(T)-T 

DT 

C4) TRIAL:T*SUM(A[2*I+l]*r(2*I*l),I,l;5); 

" 9 7 5 3 

< 04 > * T ♦ A T ♦ A T ♦ A T ♦ A T ♦ T 

H 9 7 5 3 

(C5) POWERDISP: TRUES 
(C6) RATWEIGHT(T,l)t 
(C7) RATWTLVL: 14i 
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CC«> EQ.Bm.TRIftL.DIFFi 

4 4 3 5 7 1 

(08) - T ♦ T <6 ft T ♦ 29 ft T ♦ 42 ft T ♦ 72 ft T 4 lit ft T ) 
'3 S 7 9 11 

3 S 7 t 11 3 

(T«R T *R T *(I.T «l T «l II 
3 S 7 • 11 

I 3 S 7 9 11 4 

♦ <l-KT>CT*ftT*HTtftT4ftT*ft f > 
3 5 7 9 ' 11 

a 

(C9) EXPANDEDEQ:RAT(%,T); 

6 2 8 

(D9)/R/ (4 A -K)T+(6A*6A +4A -4A K) T 
3 3 3 5 3 

2 3 2 10 
♦ ( 18 A ♦ 4 A ♦ (20 ♦ 12 A ) A ♦ 4 A ♦ ( - 6 A - 4 A ) K) T 

3 3 3 5 7 3 5 

3 4 2 2 

+ (18 A ♦ A ♦ (78 A ♦ 12 A ) A ♦ 6 A ♦ (42 ♦ 12 A ) A ♦ 4 A 
33 3 3 5 5 3 7 9 

3 12 

♦ ( - 4 A - 12 A A - 4 A ) K) T 

3 3 5 7 

4 2 3 2 

♦ (6 A ♦ (96 A ♦ 4 A ) A ♦ (60 ♦ 12 A ) A 

3 3 3 5 3 5 

2 

+ (144 A ♦ 12 A ♦ 12 A ) A ♦ (72 + 12 A ) A ♦ 4 A 

3 3 5 7 3 9 11 

4 2 2 14 

♦ (-A -12 A A-6A -12AA-4A)K)T 

3 3 5 5 3 7 9 

(CIO) C0EFF(EXPANDEDEQ,T,6); 
(D10)/R/ 4 A - K 
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(Cll) ANS3:S0LVE(%,A[3]); 
Solution 

K 
(Ell) A « - 

3 4 

(OH) [Ell] 

(C12) COEFF(EXPANDEDEQ,T,8); 

2 
<D12)/R/ 6 A ♦ 6 A ♦ 4 A - 4 A K 

3 3 5 3 

(C13) %,ANS3; 





2 




- 32 A - 12 iC + 5 SC 


(D13)/R/ 


5 




8 


(C14) SOLVE(%.A[5]); 
Solution 






2 


(E14) 


- 12 K ♦ 5 K 




5 32 


(014) 


CE14] 


(C15) /* ETC*/ 





FOR 1:3 THRU 11 STEP 2 DO 
C0EFFICIENT[I]:C0EFF(EXPANDEDEQ.T,I+3)t 

(C16) FOR 1:3 THRU 11 STEP 2 DO 

(SOL[I]:ANS:S0LVE(C0EFFICIENT[I],A[I]), 
FOR J: 1+2 STEP 2 THRU 11 DO 
COEFFICIENT J]:EV(C0EFFICIENT[J],AN5))t 

(C21) RATEXPAND:TRUEi 
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(C22) FOR 1:3 THRU 11 STEP 2 DO PRINT(RATSIHP(EV(SOL[I])))t 



[A 
3 


s 


K 

-] 
4 








[A 
5 


= 


- 


3 K 
8 


2 
5 K 
♦ -— ] 
32 








15 


K 


2 
37 K 


3 
15 K 


[A 
7 


s 


8 


*"" "* 


•• — - + 
32 


] 

128 



2 3 4 

315 K 1821 K 611 K 195 K 

[A ♦ ♦ ] 

9 16 128 256 2048 

2 3 4 5 

2835 K 2223 K 29811 K 4199 K 663 K 

11 8 8 512 1024 8192 
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Appendix IV - Glossary For The Programming Novice 



algorithm - a method, specified with sufficient precision to be programmed for a 
computer, to resolve any one of a well-defined class of problems. 

arguments - the expressions which are the values of the formal parameters when 
a function is called. 

assignment - the process of associating a value with a variable. 

atomic - (in the sense of high level programming languages) cannot be broken 

binding - the process of assigning values to the formal parameters in a function 
definition or to the local parameters in a block in such a way that, upon 
exit from the function or block, the previous values of the parameters 
are restored. 

bound variable - a variable which has been assigned a value (see binding). 

break point - a point at which a computation is temporarily suspended and control 
returned to the console, permitting the user to explore the state of the 
computation. 

bug - an error in a program caused by improper coding which may be due to 
unanticipated types of arguments being given to the program, faulty logic, 
etc. 

command line - the input line typed to MACSYMA, terminated by ; or 8. 

constant - any number or atomic symbol whose value does not vary, or an 
expression made up only of such quantities. 

CRE form - canonical rational expression form. This is one of the several internal 
representations of MACSYMA expressions (see 4.1). It is especially 
suitable for rational expressions (polynomials or ratios of polynomials). It 
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is also contagious in that whenever any expression is added to or 
multiplied by a CRE form the result will be in CRE form. 

DDT - originally a program used for debugging of other programs but modified in 
ITS to include the functions of a monitor. 

default value - the initial value of a variable before any assignments to it. 

evaluation - the process of replacing variables and function calls in an expression 
by their values. 

expansion - the transformation of a product of sums into a sum of products by 
applying the distributive laws. 

expression - a syntactically legal sequence of characters composed of constants, 
variables, functions, and operators. 

flag - a variable whose value is usually either TRUE or FALSE, e.g. NUMER. 

formal parameters - the atomic variables appearing in the function header (the 
left-hand side of a function definition). 

hashing - a method of storing sparse vectors and arrays through the use of a 
function, which for given arguments produces a -number in a range of 
possible values. 

indicator - the name of a property, e.g. GRADEF. 

internal representation - the representation of MACSYMA expressions in LISP. 

ITS - the time sharing system used on the PDP-10 at Project MAC 

LISP - a Hst processing programming language used extensively in non-numerical 
applications. The LISP in which MACSYMA resides is called MACLISP. 

local parameters - atomic variables which are bound within a function or block. 

property - a piece of information known about or associated with a variable. 
Some specific properties are used in MACSYMA for simplification and 
evaluation, e.g. the GRADEF property for SIN. 

property list - for a given variable, the set of all properties associated with the 
variable. 
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quoted string - a sequence of characters enclosed in quotation marks, used as a 
comment, message, etc. 

rational expression - a polynomial or the ratio of two polynomials. Sometimes 
used as a synonym for CRE form 

scalar - an expression which is not (or is assumed not to be) a list or matrix. 

semantics - rutes for determining the meaning of any legal (syntactically correct) 
sentence in a language. 

simplification- the process of reducing the "complexity" of an expression (relative 
to some criterion or measure) by applying known (or assumed) relations 
m the form of rules which transform the original expression into an 
"equivalent" one. 

string - a sequence of characters consisting of digits, letters, special characters 
(8,%,*) or break characters (space,tab). 

subscripted function - a type of array each of whose elements is a function 
expression. 

subscripted variable - a variable, e.g. A[01 in subscripted form. 

switch - a variable which can take on only a small number of values (usually just 
two). It is used to determine which branch of a condition to follow. 

syntax - rules for determining whether a sequence of characters is a legal 
sentence in that language. If not, then a parsing error results. In 
MACSYMA, the rules are implemented as a parsing procedure which 
converts an input string into MACSYMA's internal representation. 

terminator - a character which signals the end of a sequence of characters. In a 
MACSYMA command line the terminators are semi-colon and dollar siga 

variable - an atomic symbol. A variable that evaluates to a value is an assigned 
variable. If no value has been assigned to a variable, the variable itself 
is returned as the result of evaluation. 
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Appendix VI - MACSYMA Functions and Argument Evaluation 

Most MACSYMA functions, including all user-defined functions,* are processed 
by MACSYMA's evaluator in a straightforward manner: the arguments to the 
function are evaluated (left-to-right), the function is applied to the evaluated 
arguments, and then the result is returned. 

However, there are two classes of functions which are not subsumed under 
this simple scheme. In the first class, some or all of the arguments are NOT 
evaluated. This class includes 

ALIAS ALLOC APPENDFILE ARRAY BATCH BATCON CLOSEFILE 
COMPFILE DECLARE DEFINE DELFILE DEMO DISPFUN DISPLAY 
FASSAVE 6RADEF KILL LABELS LOADFILE LOCAL MATCHDECLARE 
NODEDECLARE PLAYBACK QPUT REMARRAY REMFILE REMFUNCTION 
REMOVE REMRULE REMVALUE RESTORE SAVE STORE STRING STRINGOUT 
TIME TRACE TRANSLATE UNSTORE UNTRACE WRITEFILE 

There is another class of functions which control the evaluation of their 
arguments; "control" involves the order of evaluation of the arguments as well as 
their form. For example, order of evaluation is important in SUM,PR0D, and the 
plotting functions; on the other hand, the EV command takes advantage of the 
structure of the arguments as well. This class includes 

CATCH ERRCATCH EV FORTRAN FORTMX FULLMAP FULLMAPL 
GRIND PROD SUBSTINPART SUBSTPART SUM 

and the plotting functions. 

In addition, certain MACSYMA "operators'* (see Appendix II) do not evaluate 
some of their arguments, such as V, V, H,B . On the other hand, MACSYMA 
constructs such as BLOCK, the various forms of DO, and logical operators such as 
AND,0R, IF...THEN...ELSE control the evaluation of their arguments. 



1. More flexibility for user-defined functions will soon be available 
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%%:[] 170,271 
%: [] 40 , 271 
%E: [] 39 , 43 
°/.EDISPFLAG: [FALSE] 184 
%EM0DE: [TRUE] 45 
%ENUMER: [FALSE] 45 
%\: [] 39 , 43 
%P\: ['] 39 , 43 
7.TH (i) 182* 

ABCONVTEST: [FALSE] 73 

ABS (X) 44* , 50, 210 

ABSBOXCHAR: [!] 44 

ACOS 47 

ACOSH 48 

AC0T47 

ACOTH 48 

ACSC 47 

ACSCH 48 

ACTIVATE (contl, cont2, ...) 148* 

ADDROW(M,l) 106* 

AIRY (X) 229* 

ALARMCLOCK (argl, arg2, arg3) 

183* 
ALGEBRAIC: [FALSE] 120 , 157 
ALGEPSILON: [10 8 ] 99 
ALGSYS ([expl, exp2, ...], [varl, 

var2, ...]) 98* 
ALIAS 156, 183* 
ALIASES: [] 156 
ALLOC 252 
ALLROOTS (poly) 97* 
ALPHABETIC 157 
APPEND (list 1, Iist2, ...) 154* 
APPENDFILE ( filename 1, filename2, 

DSK, directory) 177* 
APPLY (function, list) 151* 
APPLY1 (exp, rulel, ..., rulen) 165* 
APPLY2 (exp, rulel, ..., rulen) 165* 
APPLYB1 (exp, rulel, ..., rulen) 166* 



ARRAY (name, diml, dim 2, ..., dimk) 

14* 
ARRAYAPPLY (array,[subl, ... ,subk]) 

211* 
ARRAYINFO 15, 17, 157* 
ARRAYMAKE(name,[il,i2,...]) 151* 
ARRAYS: [] 15, 17, 156, 171 
ASEC 47 
ASECH 48 
ASIN 47 
ASINH 48 
ASKEXP: [] 147 
ASKSIGN(exp) 147* 
ASSUME (predl, pred2, ...) 146* 
AT (exp, list) 86* 
ATAN 47 
ATAN2 (Y,X) 48* 
ATANH 48 
ATOM (exp) 160* 
ATVALUE (form, list, value) 86* , 

137 
AUGCOEFMATRIX ([eql, ...], [varl, 

...]) 107* 

BACKSUBST: [TRUE] 98 

BACKTRACES] 171 

BASE: [10] 186 

BATCH 42 , 173, 176*, 237, 238*, 

239 240 
BATCHKILL: [FALSE] 240 
BATCON (argument) 176* , 237, 238, 

239 
BATCOUNT: [0] 239 
BERLEFACT: [TRUE] 63 
BERN (X) 47* 
BERNPOLY (v, n) 142* 
BESSEL (Z,A) 229* 
BETA (X, Y) 47* 
BFLOAT(X) 44*, 157 
BFLOATP(exp) 160* 
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BFTORAT: [FALSE] 114 
BFTRUNC: [TRUE] 184 
BINDTEST 157 
BINOMIAL (X, Y) 46* 
BLOCK ([vl, ... vk], statementl,..., 
statements 25* , 28, 31, 270 
BOTHCASES: [FALSE] 185 
BOTHCOEF (exp, var) 88* 
BOX (exp) 80* 
BOXCHAR: ["] 80 
BREAK (argl, ...) 170* , 182*, 271 
BREAKUP: [TRUE] 101 
BUG (message) 5* 

CABS (exp) 93* 
CALCOMPNUM: [20] 264 , 266 
CANTEN (exp) 202* 
CARG 50, 93* 
CATCH (expl,...,expn) 181* 
CAUCHYSUM[FALSE] 67 
CENTERPLOT: [] 266 
CF (exp) 142* 
CFDISREP (list) 143* 
CFEXPAND(x) 143* 
CFLENGTH: [1] 142 
CHANGEVAR <exp,f(x,y),y,x) 75* 
CHARPOLY (M, var) 109* 
CHRi <[i,j,k]> 203* 
CHR2 ([i,j],[k]) 203* 
CHRISTOF (arg) 193* 
CLOSEFILE (filenamel, filename2) 

177* 
COEFF (exp, v, n) 88* 
COEFMATRIX <[eql, ...], [varl, ...]) 

107* 
COL (M,i) 107* 
COMBINE (exp) 60* 
COMPFILE ([filespec],fl,f2 r ..) 189* , 

255 
COMPGRIND; [FALSE] 189 



COMPONENTS (tensor,exp) 200* 

CONCAT (argl, arg2, ...) 182* 

CONS (exp, list) 154* 

CONSTANT 157 

CONSTANTP (exp) 160* 

CONTENT (pi, varl, ..., varn) 118* 

CONTEXT: [GLOBAL] 149 

CONTEXTS: [[]] 149 

CONTINUE 5 , 41 

CONTOUR: [] 265 

CONTRACT (exp) 202* 

COPYUST (L) 106* 

COPYMATRtX (M) 106* 

COS 47 

COSH 48 

COT 47 

COTH 48 

COUNTER: [1] 201 

COVDIFF (exp,vl,v2,...) 207* 

CSC 47 

CSCH 48 

CURL 213 

CURSOR: [J 185 , 232 

DALEM (fields) 198* 
DEACTIVATE (contl, cont2, ...) 149* 
DEBUGMODE: [FALSE] 170 
DECLARE 35 , 1 1 1, 146*, 157*, 

170*, 199 
DEFCON (tensorl,<tensor2,tensor3>) 

201* 
DEFINE (function(arguments),body) 

38* , 180* 
DEFMATCH 156 , 163*, 171, 175 
DEFRULE 156, 165*, 171, 175 
DEFTAYLOR (function, exp) 131* 
DELETE (expl. exp2) 95* , 154 
DELFILE (file-specification)' 176* , 

243 
DEMO 173 , 176*, 237, 238, 239 
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DEMOIVRE: [FALSE] 45 , 157 
DENOM(exp) 94*. 115* 
DEPENDENCIES: [] 156 
DEPENDS 

( f unlist 1 ,varl 1st 1 ,f unlist2,varlist2^.) 

70*, 156 
DERIVABBREV: [FALSE] 69 
DERIVDEGREE <exp, dv, iv) 92* 
DERIVLIST 52 

DESCRIBE (command) 5* , 174* 
DESOLVE ([eq 1 r ..,eqn],[var 1 ,...,varn]) 

211* 
DETERMINANT (M) 109* 
DETQUT 52 

DETOUT: [FALSE] 110 , 157 
DEVICE: [] 244 
DIAGMATRIX (n. x) 106* 
DIFF 52 , 69*, 207* 
DIMENSION (equation or list of 

equations) 216* 
DIMENSION: [4] 204 
DIREC: [] 244 
DISP (expl,exp2, ...) 172* 
DISPCON (tensorl,tensor2^..) 201* 
DISPFLAG: [TRUE] 102 , 184 
DISPFORM (exp) 80* 
DISPFUN 13, 15, 171* 
DISPLAY (expl, exp2, ...) 171* 
DISPRULE (rulename) 171* 
DISPTERMS (exp) 172* 
DIV 213 

DIVIDE (pi, p2, varl, ..., varn) 117* 
DIVSUM(n,k) 144* 
DO 27 , 30, 31 
DOALLMXOPS: [TRUE] 110 
DOMXMXOPS: [FALSE] 1 1 1 
DONTF ACTOR: [] 63 
DOSCMXOPS: [FALSE] 1 1 1 
DOSCMXPLUS: [FALSE] 111 



DOTASSOC: [TRUE] 1 1 1 
DOTCONSTRULES: [TRUE] 1 1 1 
DOTDISTRIB: [FALSE] 112 
DOTEXPTSIMP: [TRUE] 112 
DOTSCRULES: [FALSE] 111 
OPART (exp, nl, ..., nk) 80* 
DSCALAR (function) 198* 
DSKALL: [] 244 
DSKGC: [FALSE] 185 , 243 
DSKUSE: [FALSE] 242 
DUMMY (il,i2,...) 201* 
DUMMYX: [#] 201 
DYNAMALLOC: [FALSE] 240 

ECHELON (M) 108* 
EINSTEIN (dis) 1 95* 
EL (F, YLIST, TLIST) 217* 
ELIMINATE 

([eq 1 ,eq2,...,eqn],[v 1 ,v2,...,vk]) 

221* 
EMATRIX (m, n, x, i, j) 106* 
ENDCONS (exp, list) 154* 
ENTERMATRIX 20 , 105* 
ENTIER (X) 44* 
ERF (X) 47* 
ERFFLAG: [TRUE] 74 
ERRCATCH (expl, exp2, ...) 181* 
ERREXP: [] 231 
ERRINTSCE: [TRUE] 222 
ERROR (argl, arg2, ...) 181* 
ERRORFUN: [FALSE] 181 , 240 
EULER (X) 47* 

EV (exp, argl, ..., argn) 51* , 82, 157 
EVAL51 

EVALS (mat,lambda) 221* 
EVEC1 (M,mu,rnodes) 220* 
EVEC2 (M,mu,modes) 220* 
EVENP(exp) 160* 
EVFLAG 157 
EVFLAG: [] 52 
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EVFUN 157 

EXAMPLE (command) 5* , 174* 

EXP (X) 45* 

EXPAND 51 ,55* 

EXPON: [0] 55 

EXPONENTIALIZE: [FALSE] 48 , 157 

EXPOP: [0] 55 

EXPRESS (expression) 214* 

EXPT 1 1 

EXPTDISPFLAG: [TRUE] 184 
EXPTISOLATE: [FALSE] 89 
EXPTSUBST: [FALSE] 82 
EZGCD(pl,p2, ...) 118* 

FACRAT:[] 195, 196, 197 

FACTCOMB (exp) 142* 

FACTLIM: [-1] 11 

FACTOR (exp) 62* , 157 

FACTORFLAG: [FALSE] 62 , 157 

FACTOROUT <exp,varl,var2,...) 65* 

FACTORSUM (exp) 64* 

FACTS (context) 148* 

FALSE: [] 43 

FASSAVE (args) 178*, 244 

FASTTIMES(pl,p2) 117* 

FEATUREP (a,f ) 146* 

FFT (rea!-array f imag-array) 226* 

FfB (X) 46* 

FILENAME: [] 243 

FILESIZE: [] 243 , 246 

FILLARRAY (array,list-or-array) 210* 

FIRST (exp) 94* , 154 

FLOAT (exp) 44* , 52 

FLOAT2BF: [FALSE] 44 

FLOAT: [] 157 

FLOATNUMP (exp) 160* 

FLUSH (expression) 208* 

FOR 27 , 30 

FORGET (predl, pred2, ...) 146* 

FORTMX (name,matrix) 174* 



FORTRAN (exp) 174* f 177 
FORTRAN: [FALSE] 177 
FORTSPACES: [FALSE] 174 
FPPREC:[16]8,44 
FREEOF (xl, x2, .... exp) 161* 
FULLMAP (fn, expl, ...) 152* 
FULLMAPL (fn, listl, ...) 153* 
FUNCTIONS: [] 12/156, 171 
FUNMAKE (namej>rgl,...,argn]) 151* 

GO (X) 229* 

Gl (X) 229* 

GAMMA (X) 46* 

GAMMAL1M: [1000000] 46 

GAUSS (MEAN.SD) 229* 

GCD (pi, p2, varl, ...) 118* 

GCD:[EZ]56, 118 

GCFACTOR (n) 63* 

GENFACT (X, Y, Z) 46* 

GENINDEX: [I] 185 

GENINDEXfl] 67 

GENMATRIX20, 105* 

GENSUMNUM[0] 67 

GET (a, i) 159* 

GETCHAR (a, i) 182* 

GFACTOR (exp) 65* 

GFACTORSUM (exp) 65* 

GLOBALSOLVE: [FALSE] 98 

GLOG (X) 46* 

GN <X,N) 229* 

GO 26 , 28 

GRAD 213 

GRADEF (f(xl, ..., xn), gl, ..., gn) 71* , 

72*, 156 
GRADEFS:[] 156 
GRAPH ([xl, x2, x3, ..., xn], [yl, y2, 

y3. .... ynl) 255* 
GRAPH2 (x-!ists,y-lists,optional-args) 

262* 
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GRAPH3D (x-lists,y-lists,z- 
listsoptional-argsjf 266* 
GRIND (arg) 174* 
GRIND: [FALSE] 173, 183 

HALFANGLES: [FALSE] 135 
HAM (ODES) 218* 
HIPOW (exp, v) 92* 
HORNER (exp, var) 116* 

10 (X) 228* 

11 (X) 228* 
IBASE: [10] 186 
IDENT(n) 106* 

IEQN (ie,unk,tech,n,guess) 224* 

iEQNPRINT: [TRUE] 225 

IF 23 

JFT (real-array,imag-array> 226* 

ILT (exp, I var, ovar) 138* 

IMAGPART 50 , 93* 

IN (X,N) 228* 

INCHAR: [C] 185 

INDEXED (tensor) 200* 

INDICES (exp) 201* 

INF: [] 43 , 73 

INFEVAL 51 

INFINITY: [] 43 

INFIX (operator, lbp[180], rbp[180], 

lpos[ANY], rpos[ANY], pos[ANY]) 

283* 
INFLAG: [FALSE] 94 
INFOUSTS:[] 156, 175, 186 
INPART <exp,nl,...,nk) 79* 
INPROD <x,y) 220* 
INTEGERP (exp) 160* 
INTEGRATE (exp, var) 73* , 74 
INTERPOLATE (func,x,a,b) 227* 
INTFACUM: [1000] 63 
INTOPOIS(A) 124* 
INTPOLABS: [0.0] 227 



INTPOLERROR: [TRUE] 227 
INTPOLREL: [0.0] 227 
INTSCE (expr.var) 222* 
IRREDUCIBLE (exp) 65* 
IS (pred) 146* 
ISOLATE (exp, var) 89* 
ISQRT (X) 45* 

JO (X) 228* 
Jl (X) 228* 
JACOBI (p,q) 144* 
JN (X,N) 228* 

KDELTA (L1,L2) 204* 

KEEPFLOAT: [FALSE] 56 , 1 14, 157 

KILL 15 , 17, 175* 

LABELS (char) 183* 

LABELS: [] 156 , 185 

LAMBDA 16 

LAPINT (exp,ovar) 139* 

LAPLACE (exp, ovar, Ivar) 137* 

LAPLACIAN 213 

LAST (exp) 95*, 154 

LASTTIME: [] 184 

LC (L) 204* 

LDEFINT 73 , 76* 

LDISP (expl,exp2 r ..) 172* 

LDISPLAY (expl,exp2,...) 172* 

LENGTH (exp) 95*, 154 

LET (prod, repl, predname, argl, 

arg2, ..., argn) 166* 
LETRAT: [FALSE] 167 
LETRULES (name) 167* 
LETSIMP(exp) 166* 
LH0SPITALLIM[4] 76 
LHS (eqn) 94* 
LIMIT 73 , 76* 
LINECHAR: [E] 185 
LINEL: [] 41 , 186, 254 
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UNENUM:[] 185,246 
LINSOLVE <[expl, exp2, ...1 [varl, 

var2, ...]) 97* 
LISTARITH: [TRUE] 21 , 110, 157 
LISTARRAY (array) 210* 
LISTCONSTVARS: [FALSE] 87 
LISTOFVARS (exp) 87* 
LISTP(exp) 161* 
LMXCHAR: [] 110 
LOADFILE 42 , 176*. 189, 245 
LOADPRINT: [TRUE] 185 
LOCAL 25, 150*. 181* 
LOG (X) 45* 
LOGARC: [FALSE] 48 
LOGCONTRACT 46 , 66*, 157 
LOGEXPAND: [FALSE] 45 , 157 
LOGNUMER: [FALSE] 46 
LOGOUT () 180*, 240 
LOGSIMP: [TRUE] 45 
LOPOW (exp, v) 92* 
LORENTZ (exp) 207* 
LPART (label, exp, nl, ..., nk) 81* 
LRICCICOM (dis) 195* 

MAIL (message) 5* 
MAKEBOX (exp) 207* 
MAKEFACT (exp) 142* 
MAKEGAMMA (exp) 142* 
MAP (fn, expl, exp2, ...) 151* 
MAPATOM (expr) 152* 
MAPERROR: [TRUE] 151 
MAPLIST (fn, expl, exp2, ...) 152* 
MATCHDECLARE (patternvar, 

predicate, ...) 162* 
MATCHFIX (operator, match, 

anspos[ANY], posfANY]) 283* 
MATRIX 20 , 105* 
MATRIXMAP (fn, M) 107* 
MATRIXP(exp) 161* 
MAX (XI, X2, ...) 44* 



MAXAPPLYDEPTH: [10000] 166 
MAXAPPLYHEIGHT: [1 0000] 1 66 
MAXNEGEX: [1000] 55 
MAXPOSEX: [1000] 55 
MAXPRIME: [489318] 143 
MAXTAYORDER: [TRUE] 127 
MEMBER (exp, list) 154* 
METRIC (G) 203* 
METRIC: [] 203 
MIN (XI, X2, ...) 44* 
MINF: [] 43 , 73 
MINFACTORIAL (exp) 141* 
MINOR (M, i, j) 107* 
MOD(p) 118* 
MODEDECLARE (yl, model, y2, 

mode2, ...) 187* 
MODRESULT; [FALSE] 119 
MODULUS: [FALSE] 118 
MOTION (dis) 194* 
MULTIGRAPH ([ [xsetl, ysetl], ..., 

[xsetn, ysetn] 1 optionaJ-args) 

255* 
MULTIPLICITIES: [FALSE] 101 
MULTTHRU (exp) 60* 
MYOPTIONS: [[]] 9 , 156 

NARY (operator, bp[ 1801 

argposfANY], pos[ANY]) 283* 

NEWDET (M,n) 109* 

NOEVAL 51 

N0FIX|operator (pos[ANY]|) 283* 

NOLABELS: [FALSE] 184 

NONDIMENSIONALIZE (list of physical 
quantities) 215* 

NONSCALAR 157 

NONSCALAR: [] 20 

NONSCALARP (exp) 160* 

NOSTRING 173 

N0T3D: [] 265 , 266 

NOUN 157 
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VII 



NOUNDISP: [FALSE] 185 

NOUNIFY (f) 80* 

NOUNS 52 

NROOTS (poly, low, high) 96* 

NTERMS (exp) 95* 

NTERMSGO 195* 

NTERMSRCIO 195* 

NUM (exp) 94* ,115* 

NUMBERP(exp) 161* 

NUMER 52 

NUMER:[] 157, 159 

NUMERVAL (varl, expl, var2, exp2, 

...) 159* 
NUMFACTOR (exp) 91* 
NUSUM (exp,var,low,high) 68* 
NZETA (Z) 229* 
NZETAI (Z) 229* 
NZETAR (Z) 229* 

ODDP (exp) 160* 
ODE2 (diffeq,depvar,indvar) 77* 
OFF: [] 238 
ON: [] 238 

OPTIMIZE (exp) 187* , 248 
OPTIONSET: [FALSE] 184 
ORDERGREAT 156, 179* 
ORDERGREATP (expl,exp2) 179* 
ORDERLESS 156, 179* 
ORDERLESSP (expl,exp2) 179* 
OUTCHAR:[D] 185 
OUTOFPOIS(A) 124* 

PARAMPLOT (fl(t),f2(t),gow,hlgh) 

255* 
PARAMPLOT2 (x-exprs,y- 

exprs,variable,var-range,optional- 

args) 263* 
PART (exp, nl, ..., nk) 78* 
PARTFRAC (exp, var) 62* 
PARTITION (exp, var) 66* 



PARTSWITCH: [FALSE] 85 

PERSPECTIVE: [TRUE] 266 

PFEFORMAT: [FALSE] 184 

PICKAPART (exp,depth) 90* 

PIECE: [] 85 

PLAYBACK (arg) 173*, 183 

PLOG (X) 46* 

PLOT (F<x), x, low, high) 254* 

PLOT2 (y-exprs,variable,var- 

range,optionals-args) 260* , 262* 
PL0T3D (z-exprs,x-var,var-range,y- 

var,varl-range,optional-args) 

265* 
PLOTBELL: [TRUE] 264 
PLOTBOTMAR: [320] 267 
PLOTHEIGHT: [] 186 , 254 
PL0TLFTMAR:[128]267 
POiSDIFF (A, B) 125* 
POISEXPT (A, B) 124* 
POISINT(A, B) 125* 
P0ISLIM[5] 127 

POISMAP (series, sinfn, cosfn) 1 25* 
POISPLUS (A, B) 1 24* 
POISSIMP(A) 124* 
POISSUBST (A, B, C) 125* 
POISTIMES (A, B) 124* 
POISTRIMO 124* 
POLARFORM 50 , 93* 
POLARTORECT (magnitude- 

array,phase-array) 226* 
POLYDBOPMP (poly,var) 104* 
POLYFACTOR: [FALSE] 97 
POLYSIGN (X) 44* 
POSTFIX (operator, lbp[180], 

lpos[ANY], pos[ANY]) 283* 
POTENTIAL (givengradient) 215* 
POWERDISP: [FALSE] 185 
POWERSERIES (exp, var, pt) 132* 
PRED 52 
PRED: [] 157 
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PREDERROR: [TRUE] 24 , 146, 171, 

270 
PREFIX (operator, rbp[180], 

rpos[ANY], posfANY]) 283* 
PRIME (n) 143* 
PRIMER 5* 

PRINT (expl, exp2, ...) 172* 
PRINTPOIS (A) 124* 
PRINTPROPS (a, i) 158* 
PRODUCT (exp, ind, lo, hi) 68* 
PROGRAMMODE: [FALSE] 102 
PROPERTIES (a) 158* 
PROPS: [] 156 
PROPVARS (prop) 156* 
PSEXPAND: [FALSE] 121 
PSI (X) 47* 
PUT (a, p, i) 158* 

QPUT(a, p, i) 158* 

QUAL (<expression>, <variables>) 

219* 
QUIT <) 180* , 240 
QUNIT (n) 144* 
QUOTIENT (pi, p2, varl, ...) 117* 

RADCAN (exp) 58* , 157 
RADPRODEXPAND: [TRUE] 45 , 59 
RADSUBSTFLAG: [FALSE] 83 
RAISERIEMANN (dis) 197* 
RANDOM (X) 46* 
RANK (M) 108* :*"■• 

RAT (exp, vl, ..., vn) 113* 
RATALGDENOM- [TRUE] 120, 157 
RATCOEF (exp, v, n) 88* 
RATDENOM (exp) 115* 
RATDENOMDIVIDE: [TRUE] 56 
RATDIFF (exp, var) 119* 
RATDISREP (exp) 115* 
RATEINSTEIN: [] 195 
RATEPSILON: [2.0E-8] 113 



RATEXPAND (exp) 56* , 114, 157 
RATEXPAND: [FALSE] 56 
RATFAC: [FALSE] 34 , 114 
RATMX: [FALSE] 110 
RATNUMER (exp) 115* 
RATNUMP(exp) 161* 
RATP(exp) 161* 
RATPRINT: [TRUE] 114 
RATRIEMAN:[] 196 
RATSIMP(exp) 57* , 61, 114, 157 
RATSIMPEXPONS: [FALSE] 57 
RATSUBST (a, b, c) 83* 
RATVARS (varl, var2, ..., varn) 113* 
RATVARS:[] 113 
RATWEIGHT (vl, wl, ..., vn, wn) 

116* 
RATWEIGHTS: [[]] 116 
RATWEYLf] 197 
RATWTLVL : [FALSE] 116 
READ (stringl, ...) 180* 
READONLY (stringl,...) 180* 
REALONLY: [TRUE] 99 
REALPART 50 , 92* 
REALROOTS (poly, bound) 96* 
REALROOTS: [TRUE] 99 
REALZERO (poly,any thing) 230* 
REARRAY (array,diml, ... ,dimk) 21 1* 
RECTFORM 50 , 93* 
RECTTOPOLAR (real-array,imagr 

array) 226* 
REFCHECK: [FALSE] 171 , 270 
REM(a,i) 159* 

REMAINDER (pi, p2, varl, ...) 117* 
REM ARRAY 15, 17, 175* 
REMBOX (exp, arg) 81* 
REMCOMPS (tensor) 200* 
REMCON ( tensor l f tensor 2,...) 202* 
REMFILEO 178* ,'243, 247 
REMFUNCTION(fl, f2, ...) 174* , 175 
REMLET (prod, name) 167* 
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REMOVE (al, fl, a2, 12, ...) 146* , 

158*, 174*, 271 
REMRULE (function, rulename) 175* 
REMTRACEO 170*, 270 
REMVALUE 15, 174*, 175 
RENAME (exp, <count>) 201* 
RESET () 182* 
RESIDUE (exp, var, val) 77* 
REST (exp, n) 95* , 154 
RESTORE (file-specification) 178* , 

248 
RESULTANT (pi, p2, var) 118* 
RETURN 26 , 28, 30 
REVEAL <exp,depth) 91* , 172* 
REVERSE (list) 154* 
REVERSE: [FALSE] 266 
RHS (eqn) 94* 
RICCICOM (dis) i94* 
RIEMANN(dis) 196*, 204* 
RINVARIANTO 197* 
RISCH (exp, var) 74* 
RMXCHAR: [] 110 
ROMBERG (f,a,b,lim) 225* 
ROOTSCONTRACT 45 , 66* 
ROOTSEPSILON: [1.0E-7] 96 
ROW (M, i) 107* 
RULES: [] 156, 162 

SAVE 42 , 173, 177*, 242, 244, 247 
SAVEDEF: [TRUE] 189 
SAVEFACTORS: [FALSE] 63 
SCALARMATRIXP; [TRUE] 111 
SCALEFACTORS 

(coordinatetransform) 214* 
SCANMAP (function,exp) 153* 
SCURVATUREO 195* 
SEC 47 
SECH 48 

SEND (message) 4* 
SETCHECK: [FALSE] 171 



SETCHECKBRgAK; jmSE] 17* 

SETElMX(k,i r |,f« f t0>* 

SHOWTEN(exp) 200* 

SHOWTIME: [FALSE] 41 , 183 

SIGN (exp) 147* 

SIGNUM (X) 44* ,210 

SIMP 51 

SIMP: [] 157 

SIMPSON (f,a,b,n) 225* 

SIMPSUM:[] 157 

SIMTRAN (mat) 221* 

SIN 47 

SINH 48 

SOLVE 53, 100*, 101* 

SOLVEDECOMPOSES: [TRUE] 102 

SOLVEEXPLICIT: [FALSE] 102 

SOLVEFACTORS: [TRUE] 101 

SOLVERADCAN: [FALSE] 101 

SOLVETRIGWARN: [TRUE] 102 

SORT (list,optional-predicate) 180* 

SPARSE: [FALSE] 1 1 1 

SQFR (exp) 65* 

SQRT(X) 45*, 144 

SQRTDISPFLAG: [TRUE] 184 

SRRAT(exp) 121* 

STAP (OBJECTIVE, LEZEROS, 

EQZEROS, DECISIONVARS) 217* 
STARDISP: [FALSE] 185 
STATUS (arg) 182* 
STORE (args) 178* , 242, 244 
STOREMUM: [] 243 
STRING Tlxp) 173* , 183, 231 
STRINGOUT 116 , 173, 177*, 183 
SUBMATRIX (ml, ..., M, nl, ,..) 107* 
SUBST(a, b, c) 81* 
SUBSTINPART (x, exp, nl, ...) 84* 
SUBSTPART (x, exp, nl, ..., nk) 83* 
SUBVARP(exp) 160* 
SUM (exp, ind, lo, hi) 66* 
SUMSPUTFACT: [TRUE] 142 
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TAN 47 
TANH 48 
TAYLOR 



(exp,[var 1 ,pt 1 ,ordl l[var2,pt2,ord21...) 

121* , 127*, 129*, 130* 
TAYLORDEPTH: [3] 127 
TAYLORINFO (exp) 131* 
TELLRAT (polyl,...,polyn)' 120* 
TELLSIMP 156 , 162*. 171, 175 
TELLSIMPAFTER 156 ,162*, 171, 

175 
THROW (exp) 182* 
TIME (Dil, Di2, ...) 180* 
TLDEFINT <exp,var,low,high) 77* 
TLIMIT (exp,var,val,dir) 76* 
TLIMSWITCH[FALSE] 76 
TOPLEVEL: [] 271 
TOTALDISREP (exp) 115* 
TOTIENT (n) 144* 
TRACE (namel, name 2, ...) 170* 
TRANSBIND: [TRUE] 189 
TRANSLATE (fl, f2, ...) 188* , 255 
TRANSLATE: [FALSE] 188 
TRANSPOSE (M) 108* 
TRANSRUN: [TRUE] 189 "< 
TRIANGULARIZE (M) 108* 
TRIGEXPAND (exp) 134* , 157 
TRIGEXPAND: [FALSE] 135 , 157 
TRIGREDUCE (exp, var) 135* , 157 
TRIGSIGN: [TRUE] 48 
TRUE: [] 43 
TSETUP () 191* 
TTYOFF: [FALSE] 41 



UEVEC <M,mu,modes) 220* 
UNAME: [] 244 
UNDIFF (exp) 207* 
UNITRAMP 210 
UNITSTEP 210 
UNKNOWN (exp) 55* 
UNLABELED: [] 81 
UNORDER () 179* 
UNSTORE (namel,...) 178* 
UNSUM (fun,n) 68* 
UNTRACE (namel, ...) 170* 

VALUES: [] 10, 156 
VECTORPOTENTIAL (givencurl) 215* 
VECTORSIMP (vectorexpression) 

213* 
VERBIFY (f) 80* 
VERBOSE: [FALSE] 132 
VERSION: [267] 186 
VIEWPT: [] 266 

WEYL(dis) 197* 

WRITEFILE (DSK, directory) 177* 

XAXIS: [FALSE] 254 
XTHRU(exp) 61* 

YAXIS: [FALSE] 254 
YT(f,m,n) 198* 

ZERO (tensor) 208* 
ZEROBERN: [TRUE] 47 
ZEROEQUIV (exp,var) 148* 
ZETA (X) 47* 
ZUNDERFLOW: [TRUE] 12 

3D: [] 265 



